Purchase

The WaafiPay API supports multiple payment actions through a unified endpoint. For Purchase actions, use the serviceName parameter with different values to initiate a purchase, cancel a purchase, or refund a purchase.

1. Purchase

serviceName: API_PURCHASE
Purpose: Charges the payer's account, completing the payment.
Request Example: Set serviceName to API_PURCHASE and customize payerInfo and transactionInfo as required.

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	Data Type	Length	Presence	Description
`schemaVersion`	String	5	Constant	API schema version (e.g., "1.0")
`requestId`	String	36 (UUID)	Required	Unique request identifier (e.g., UUID)
`timestamp`	String	20	Required	Date and time of the request
`channelName`	String	3-10	Constant	The channel through which the request was made
`serviceName`	String	15-25	Constant	The name of the service being called (e.g., API_PURCHASE)
`merchantUid`	String	7-15	Required	Unique identifier provided by WaafiPay upon merchant account setup
`apiUserId`	String	7-15	Required	API user identifier for the merchant
`apiKey`	String	20-40	Required	API key for request authentication
`paymentMethod`	String	5-20	Required	Payment method being used (e.g., MWALLET_ACCOUNT)
`payerInfo.accountNo`	String	10-20	Required	Account number of the payer
`transactionInfo.referenceId`	String	1-50	Required	Your unique internal transaction or order reference (e.g. order number, invoice ID, or bill number). Used for querying and reconciliation. Only letters, numbers, dashes, underscores, and dots are allowed.
`transactionInfo.invoiceId`	String	1-50	Required	Invoice ID can be the same as the `referenceId`
`transactionInfo.amount`	Number	N/A	Required	Transaction Amount to be charged for the customer (numeric) in two decimal places
`transactionInfo.currency`	String	3	Required	ISO 4217 currency code for the transaction (e.g. USD, SLSH, DJF)
`transactionInfo.description`	String	0-255	Optional	Description of the transaction (e.g., random sentence)

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

serviceName: API_CANCELPURCHASE
Purpose: Reverses the payment for a previously completed purchase.
Request Example: Set serviceName to API_CANCELPURCHASE and include the transactionId of the original transaction.

Request Structure

POST /asm
{
  "schemaVersion": "1.0",
  "requestId": "{{$guid}}",
  "timestamp": "{{$timestamp}}",
  "channelName": "WEB",
  "serviceName": "API_CANCELPURCHASE",
  "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"
  }
}

Summary:

Response: Contains the result of the cancellation, including transaction status (approved), description, and the associated transaction ID.

On this page