API reference

Purchase

Purchase & Reversal API Reference

Use the unified /asm endpoint with different serviceName values to complete or reverse a purchase.

1. Purchase

API_PURCHASECharges the payer's account and completes the payment.

Request structure

POST /asm
{
  "schemaVersion": "1.0",
  "requestId": "{{$guid}}",
  "timestamp": "{{$timestamp}}",
  "channelName": "WEB",
  "serviceName": "API_PURCHASE",
  "serviceParams": {
    "merchantUid": {{MERCHANT_UID}},
    "apiUserId": {{API_USER_ID}},
    "apiKey": {{API_KEY}},
    "paymentMethod": "MWALLET_ACCOUNT",
    "payerInfo": { "accountNo": "252611111111" },
    "transactionInfo": {
      "referenceId": "{{$randomBankAccount}}",
      "invoiceId": "154",
      "amount": "10",
      "currency": "USD",
      "description": "{{$randomLoremSentence}}"
    }
  }
}

Request parameters

Parameter	Type	Length	Presence	Description
`schemaVersion`	String	5	Constant	API schema version, such as 1.0
`requestId`	String	36 (UUID)	Required	Unique request identifier
`timestamp`	String	20	Required	Request date and time
`channelName`	String	3–10	Constant	Originating channel
`serviceName`	String	15–25	Constant	API_PURCHASE
`merchantUid`	String	7–15	Required	Merchant identifier issued during setup
`apiUserId`	String	7–15	Required	Merchant API user identifier
`apiKey`	String	20–40	Required	Request-authentication key
`paymentMethod`	String	5–20	Required	For example, MWALLET_ACCOUNT
`payerInfo.accountNo`	String	10–20	Required	Payer number in full international format
`transactionInfo.referenceId`	String	1–50	Required	Unique merchant transaction or order reference
`transactionInfo.invoiceId`	String	1–50	Required	Invoice ID; may match referenceId
`transactionInfo.amount`	Number	N/A	Required	Transaction amount with up to two decimal places
`transactionInfo.currency`	String	3	Required	ISO 4217 code, such as USD, SLSH, or DJF
`transactionInfo.description`	String	0–255	Optional	Transaction description

Response structure

{
  "schemaVersion": "1.0",
  "timestamp": "2024-11-05 09:04:44.741",
  "responseId": "12314",
  "responseCode": "2001",
  "errorCode": "0",
  "responseMsg": "RCS_SUCCESS",
  "params": {
    "accountNo": "252611****1111",
    "accountType": "MWALLET_ACCOUNT",
    "state": "APPROVED",
    "merchantCharges": "0.1",
    "referenceId": "1234",
    "transactionId": "1268666",
    "issuerTransactionId": "ISR0011268666",
    "txAmount": "10.0"
  }
}

2. Purchase reversal

API_REVERSALReverses an eligible completed purchase using its original transactionId.

Request structure

POST /asm
{
  "schemaVersion": "1.0",
  "requestId": "{{$guid}}",
  "timestamp": "{{$timestamp}}",
  "channelName": "WEB",
  "serviceName": "API_REVERSAL",
  "serviceParams": {
    "merchantUid": {{MERCHANT_UID}},
    "apiUserId": {{API_USER_ID}},
    "apiKey": {{API_KEY}},
    "transactionId": "{{transactionId}}",
    "description": "Cancelled"
  }
}

Response structure

{
  "schemaVersion": "1.0",
  "timestamp": "2024-11-05 09:07:48.786",
  "responseId": "12314",
  "responseCode": "2001",
  "errorCode": "0",
  "responseMsg": "RCS_SUCCESS",
  "params": {
    "description": "success",
    "state": "approved",
    "transactionId": "1268667",
    "referenceId": "1234"
  }
}