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": "25261111111"
        },
        "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 merchant identifier
`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	Reference ID for the transaction
`transactionInfo.invoiceId`	String	1-50	Required	Invoice ID
`transactionInfo.amount`	Number	N/A	Required	Transaction amount (numeric)
`transactionInfo.currency`	String	3	Required	Currency code (e.g., "USD")
`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"
  }
}

Response Parameters

Parameter	Data Type	Length	Description
`schemaVersion`	String	5	API schema version (e.g., "1.0")
`timestamp`	String	20	Date and time of the response
`responseId`	String	1-50	Unique response identifier
`responseCode`	String	1-10	Response code indicating the result of the request
`errorCode`	String	1-5	Error code (e.g., "0" for no error)
`responseMsg`	String	0-255	Human-readable message for the response
`params.accountNo`	String	10-20	Account number of the payer
`params.accountType`	String	5-20	Type of the account (e.g., "MWALLET_ACCOUNT")
`params.state`	String	1-15	State of the transaction (e.g., "APPROVED")
`params.merchantCharges`	Number	N/A	Merchant charges (numeric)
`params.referenceId`	String	1-50	Reference ID for the transaction
`params.transactionId`	String	1-50	Transaction ID returned from the transaction
`params.issuerTransactionId`	String	1-50	Issuer transaction ID
`params.txAmount`	Number	N/A	Amount for the transaction (numeric)

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 and referenceId of the original transaction.

Request Structure

POST /asm
{
  "schemaVersion": "1.0",
  "requestId": "{{$randomUUID}}",
  "timestamp": "{{$timestamp}}",
  "channelName": "WEB",
  "serviceName": "API_CANCELPURCHASE",
  "serviceParams": {
    "merchantUid": {{MERCHANT_UID}},
    "apiUserId": {{API_USER_ID}},
    "apiKey": {{API_KEY}},
    "paymentMethod": "MWALLET_ACCOUNT",
    "transactionId": "{{transactionId}}",
    "referenceId": "{{referenceId}}",
    "description": "Cancelled"
  }
}

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_CANCELPURCHASE)
`merchantUid`	String	7-15	Required	Unique merchant identifier
`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)
`transactionId`	String	1-50	Required	Original Transaction ID from previous purchase
`referenceId`	String	1-50	Optional	Reference ID for the transaction
`description`	String	0-255	Optional	Description of the action (e.g., "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"
  }
}

Purchase Reversal Response Parameters

Parameter	Data Type	Length	Description
`schemaVersion`	String	5	API schema version (e.g., "1.0")
`timestamp`	String	20	Date and time of the response
`responseId`	String	1-50	Unique response identifier
`responseCode`	String	1-10	Response code indicating the result of the request
`errorCode`	String	1-5	Error code (e.g., "0" for no error)
`responseMsg`	String	0-255	Human-readable message for the response
`params.description`	String	0-255	Description of the response (e.g., "success")
`params.state`	String	1-15	State of the transaction (e.g., "approved")
`params.transactionId`	String	1-50	Transaction ID returned from the transaction
`params.referenceId`	String	1-50	Reference ID returned from the transaction

Summary:

Request Key Parameters: Includes details for canceling the purchase, such as transactionId, referenceId, and the cancellation description (e.g., "Cancelled").
Response Key Parameters: Contains the result of the cancellation, including transaction status (approved), description, and the associated transaction IDs.

On this page