The PreAuthorization API in WaafiPay enables full control over enabling seamless control over the initiation, cancellation, and commitment of funds. By specifying different values in the serviceName parameter, clients can perform distinct actions such as placing a hold on a user's account (PreAuthorization), voiding a held amount before it is captured (Cancellation), or finalizing the transaction to capture the reserved funds (Commitment). This streamlined approach simplifies integration while maintaining flexibility for transaction lifecycle management.

Actions

1. PreAuthorization

serviceName: API_PREAUTHORIZE
Purpose: Authorizes the specified amount on the user's account without executing the actual deduction.

Request Structure

POST /asm
{
  "schemaVersion": "1.0",
  "requestId": "{{$guid}}",
  "timestamp": "{{$timestamp}}",
  "channelName": "WEB",
  "serviceName": "API_PREAUTHORIZE",
  "serviceParams": {
    "merchantUid": "{{MERCHANT_UID}}",
    "apiUserId": {{API_USER_ID}},
    "apiKey": "{{API_KEY}}",
    "paymentMethod": "MWALLET_ACCOUNT",
    "payerInfo": {
      "accountNo": "25261111111"
    },
    "transactionInfo": {
      "referenceId": "22043",
      "amount": "1",
      "currency": "USD",
      "description": "Payment for order #22043"
    }
  }
}

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	5-20	Constant	Channel of the request (e.g., "WEB")
`serviceName`	String	15-25	Constant	The name of the service being called
`merchantUid`	String	7-15	Required	Unique merchant identifier provided by WaafiPay upon merchant account setup
`apiUserId`	String	7-15	Required	Unique identifier provided by WaafiPay store account setup
`apiKey`	String	20-40	Required	Unique alphanumeric string assigned by WaafiPay store account setup
`payerInfo.accountNo`	String	10-20	Required	Account number of the payer
`paymentMethod`	String	5-20	Required	Payment method being used (e.g., MWALLET_ACCOUNT)
`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.referenceId`	String	10-30	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.description`	String	5-100	Optional	A short description of the order or item being purchased by the customer, e.g. "Payment for order #22043" or "Subscription to premium plan".

Response structure

{
  "schemaVersion": "1.0",
  "timestamp": "2024-11-05 08:52:06.287",
  "responseId": "12314",
  "responseCode": "2001",
  "errorCode": "0",
  "responseMsg": "RCS_SUCCESS",
  "params": {
    "state": "APPROVED",
    "referenceId": "1234",
    "transactionId": "1268664",
    "txAmount": "1.0"
  }
}

Summary:

Request Parameters: Identifiers for the transaction and the user, including service details, payment method, and the amount.
Response Parameters: The result of the transaction, including the response code, message, and transaction state.

2. Commit

serviceName: API_PREAUTHORIZE_COMMIT
Purpose: Finalizes a previously preauthorized transaction, confirming the reserved funds.
Request Example: Set serviceName to API_PREAUTHORIZE_COMMIT and include the transactionId that was returned from the preauthorization step.

Request Structure

POST /asm
{
  "schemaVersion": "1.0",
  "requestId": "{{$randomUUID}}",
  "timestamp": "{{$timestamp}}",
  "channelName": "WEB",
  "serviceName": "API_PREAUTHORIZE_COMMIT",
  "serviceParams": {
    "merchantUid": {{MERCHANT_UID}},
    "apiUserId": {{API_USER_ID}},
    "apiKey": {{API_KEY}},
    "transactionId": "1234",
    "description": "Order #1234 committed"
  }
}

Response Structure

{
  "schemaVersion": "1.0",
  "timestamp": "2024-11-05 08:55:45.828",
  "responseId": "12314",
  "responseCode": "2001",
  "errorCode": "0",
  "responseMsg": "RCS_SUCCESS",
  "params": {
    "description": "success",
    "state": "approved",
    "transactionId": "1268664",
    "referenceId": "1234"
  }
}

3. Cancellation

serviceName: API_PREAUTHORIZE_CANCEL
Purpose: Cancels a previously preauthorized transaction, releasing the reserved funds.

Request Structure

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

Request Parameters

Parameter	Data Type	Length	Presence	Description
`transactionId`	String	1-50	Required	Transaction ID returned from the original transaction
`description`	String	0-255	Optional	Description of the action (e.g., "Booking order canceled")

Response

{
  "schemaVersion": "1.0",
  "timestamp": "2024-11-05 08:59:59.986",
  "responseId": "12314",
  "responseCode": "2001",
  "errorCode": "0",
  "responseMsg": "RCS_SUCCESS",
  "params": {
    "description": "success",
    "state": "approved",
    "transactionId": "1268665",
    "referenceId": "1234"
  }
}

PreAuthorization

On this page