Payment Instrument
The Payment Instrument APIs offer a secure solution for managing payment instruments and associated details. These APIs enable the creation, retrieval, and updating of payment instruments.
info
- Authentication required: These endpoints require authentication. To learn how to authenticate, see our authentication documentation.
- Sample requests & responses: To test these endpoints with sample requests, use our Postman collection
- Swagger file: To view definitions for these endpoints, see our swagger file
POST Create Payment Instrument
Securely stores payment_details and returns a payment_token.
Endpoint
/payment_instrument
Sample Messages
Sample Request
{
"payment_verification": {
"verification_type": "card",
"details_format": "details",
"verification_details": {
"verification": {
"card_verification_code": "123"
}
}
},
"payment_instrument": {
"details_format": "details",
"instrument_type": "card",
"instrument_details": {
"instrument": {
"card_number": "4242888877774321",
"expiration_date": "12/28",
"card_verification_code": "123"
},
"payer": {
"details_format": "details",
"your_entity_refernce": "string",
"entity_type": "person",
"entity_details": {
"name": {
"first": "Kevin",
"middle": "",
"last": "Roger",
"suffix": "",
"prefix": ""
},
"addresses": [
{
"type": "billing",
"details": {
"line_1": "2100 Alamo Rd",
"line_2": "Suite T",
"line_3": "mailbox 123",
"postal_code": "75080",
"city": "Richardson",
"state_region_province": "TX",
"country": "US",
"your_address_reference": "string"
}
}
],
"email": "user@example.com",
"phone_number": {
"type": "mobile",
"details": {
"country_code": "string",
"unformatted_number": "123456789",
"formatted_number": "string"
},
"your_phone_number_reference": "string"
}
}
},
"saved_for_later": true,
"your_instrument_reference": "hello world"
}
}
}
Sample Response
{
"instrument_type": "card_instrument",
"instrument_details": {
"instrument_id": "3c803e39-7460-4f21-b4ba-6c3a3f57e062",
"instrument": {
"card_bin": "424288",
"card_last_four": "4321",
"card_number": "",
"expiration_date": "12/28",
"your_instrument_reference": "hello world"
},
"payer": {
"entity": {
"details": {
"digital_addresses": [
{
"details": "user@example.com",
"type": "email"
}
],
"names": [
{
"details": "Kevin",
"type": "first_name"
},
{
"details": "Roger",
"type": "last_name"
}
],
"phone_numbers": [
{
"details": {
"country_code": "string",
"formatted_number": "string",
"e164_number": "123456789"
},
"type": "mobile"
}
],
"physical_addresses": [
{
"details": {
"city": "Richardson",
"country": "US",
"line_1": "2100 Alamo Rd",
"line_2": "Suite T",
"line_3": "mailbox 123",
"postal_code": "75080",
"state_region_province": "TX"
},
"type": "billing",
"your_physical_address_reference": "string"
}
]
},
"token_ref": "e901c931-bdaf-4e78-89b2-d3380224e88c",
"type": "person"
}
}
},
"saved_for_later": true,
"your_instrument_reference": ""
}
GET Payment Details
Returns a payment_token including details, related details, payer entity and status.
This endpoint requires authentication.
Endpoint
/payment_instrument/{payment_token}
Parameters
| Name | Value | Required | Explanation |
|---|---|---|---|
| Instrument Id | {instrumentId} | Yes | Id of the payment instrument whose status is being reported |
Sample Messages
Sample Response
{
"instrument_type": "card_instrument",
"instrument_details": {
"instrument_id": "3c803e39-7460-4f21-b4ba-6c3a3f57e062",
"instrument": {
"card_bin": "424288",
"card_last_four": "4321",
"card_number": "",
"expiration_date": "12/28",
"your_instrument_reference": "hello world"
},
"payer": {
"entity": {
"details": {
"digital_addresses": [
{
"details": "user@example.com",
"type": "email"
}
],
"names": [
{
"details": "Kevin",
"type": "first_name"
},
{
"details": "Roger",
"type": "last_name"
}
],
"phone_numbers": [
{
"details": {
"country_code": "string",
"formatted_number": "string",
"e164_number": "123456789"
},
"type": "mobile"
}
],
"physical_addresses": [
{
"details": {
"city": "Richardson",
"country": "US",
"line_1": "2100 Alamo Rd",
"line_2": "Suite T",
"line_3": "mailbox 123",
"postal_code": "75080",
"state_region_province": "TX"
},
"type": "billing",
"your_physical_address_reference": "string"
}
]
},
"token_ref": "22cca2b3-44a3-467b-8d59-ef1f76bdc640",
"type": "person"
}
}
},
"saved_for_later": false,
"your_instrument_reference": ""
}
POST Update Payment
Securely updates payment_details for the payment_token
Endpoint:
/payment_instrument/{payment_token}
Parameters
| Name | Value | Required | Explanation |
|---|---|---|---|
| Instrument Id | {instrumentId} | Yes | Id of the payment instrument whose status is being reported |
Sample Messages
Sample Request
{
"payment_verification": {
"verification_type": "card",
"details_format": "details",
"verification_details": {
"verification": {
"card_verification_code": "123"
}
}
},
"payment_instrument": {
"details_format": "details",
"instrument_type": "card",
"instrument_details": {
"instrument": {
"card_number": "4242888877774321",
"expiration_date": "12/28",
"card_verification_code": "123"
},
"payer": {
"details_format": "details",
"your_entity_refernce": "string",
"entity_type": "person",
"entity_details": {
"name": {
"first": "Kevin",
"middle": "",
"last": "Roger",
"suffix": "",
"prefix": ""
},
"addresses": [
{
"type": "billing",
"details": {
"line_1": "2100 Alamo Rd",
"line_2": "Suite T",
"line_3": "mailbox 123",
"postal_code": "75080",
"city": "Richardson",
"state_region_province": "TX",
"country": "US",
"your_address_reference": "string"
}
}
],
"email": "user@example.com",
"phone_number": {
"type": "mobile",
"details": {
"country_code": "string",
"unformatted_number": "123456789",
"formatted_number": "string"
},
"your_phone_number_reference": "string"
}
}
},
"saved_for_later": false,
"your_instrument_reference": "hello world"
}
}
}
Sample Response
{
"instrument_type": "card_instrument",
"instrument_details": {
"instrument_id": "3c803e39-7460-4f21-b4ba-6c3a3f57e062",
"instrument": {
"card_bin": "424288",
"card_last_four": "4321",
"card_number": "",
"expiration_date": "12/28",
"your_instrument_reference": "hello world"
},
"payer": {
"entity": {
"details": {
"digital_addresses": [
{
"details": "user@example.com",
"type": "email"
}
],
"names": [
{
"details": "Kevin",
"type": "first_name"
},
{
"details": "Roger",
"type": "last_name"
}
],
"phone_numbers": [
{
"details": {
"country_code": "string",
"formatted_number": "string",
"e164_number": "123456789"
},
"type": "mobile"
}
],
"physical_addresses": [
{
"details": {
"city": "Richardson",
"country": "US",
"line_1": "2100 Alamo Rd",
"line_2": "Suite T",
"line_3": "mailbox 123",
"postal_code": "75080",
"state_region_province": "TX"
},
"type": "billing",
"your_physical_address_reference": "string"
}
]
},
"token_ref": "22cca2b3-44a3-467b-8d59-ef1f76bdc640",
"type": "person"
}
}
},
"saved_for_later": false,
"your_instrument_reference": ""
}
HTTP Responses
| HTTP Status | Description |
|---|---|
| 200 | Returns a payment_token including details, related details, payer entity, and status. |
| 400 | The request error response provides error information about the most recent API request which contained a schema error. Please review the error fields to determine how to resolve this error. |
| 500 | An error occurred either within /charge or externally in a system connected to /charge. Please notify DataMesh IT Support via itsupport@datameshgroup.com. |