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
Instrument data structure
The shape of the instrument payload — i.e. the actual payment details carried inside a payment instrument — is template-resolved. Each payment instrument references an instrument-type template that defines the JSON schema for that variant.
Template keys follow a <method>_<region> convention. Examples of templates that may apply to a payment instrument depending on the merchant's region and processor configuration:
| Template key | Variant |
|---|---|
card_global | Card payment, global card schemes |
wallet_indonesia | Indonesian wallet methods |
bank_transfer_singapore | Singapore bank transfer |
The required fields and validation rules for each variant are defined by the resolved template's JSON schema. Merchants integrating against a specific region or payment method should refer to the integration material provided when their account is provisioned for the exact instrument payload they should send.
note
The OpenAPI specification treats instrument as a generic field because its concrete shape is template-driven and depends on the merchant's processor configuration. The processor and the resolved template are determined at the platform level; merchants do not configure them directly through the Charge API.
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 DMG IT Support via itsupport@datameshgroup.com. |