The WaafiPay API allows for managing preauthorized transactions through a single endpoint, utilizing different values in the serviceName parameter to perform specific actions: Preauthorization, Cancellation, and Commitment of transactions.

Actions

1. PreAuthorization

serviceName: API_PREAUTHORIZE
Purpose: Reserves funds for a specific amount on a user’s account without immediately charging.
Request Example:Set serviceName to API_PREAUTHORIZE and customize the payerInfo and transactionInfo as required.

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": "{{$randomBankAccount}}",
      "invoiceId": "INV99222255",
      "amount": "1",
      "currency": "USD",
      "description": "test preauth"
    }
  }
}

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
`apiUserId`	String	7-15	Required	API user identifier for the merchant
`apiKey`	String	20-40	Required	API key for request authentication
`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 (numeric)
`transactionInfo.currency`	String	3	Required	Currency code (e.g., "USD")
`transactionInfo.referenceId`	String	10-30	Required	Unique reference ID for the transaction
`transactionInfo.invoiceId`	String	10-30	Optional	Invoice identifier
`transactionInfo.description`	String	5-100	Optional	Description of the transaction

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"
  }
}

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.state`	String	1-15	State of the transaction (e.g., "APPROVED")
`params.referenceId`	String	1-50	Reference ID returned from the transaction
`params.transactionId`	String	1-50	Transaction ID returned from the transaction
`params.txAmount`	Number	N/A	Amount for the transaction (numeric)

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. Cancellation

serviceName: API_PREAUTHORIZE_CANCEL
Purpose: Cancels a previously preauthorized transaction, releasing the reserved funds.
Request Example: Set serviceName to API_PREAUTHORIZE and customize the payerInfo and transactionInfo as required.

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": "{{$randomBankAccount}}",
      "invoiceId": "INV99222255",
      "amount": "1",
      "currency": "USD",
      "description": "test preauth"
    }
  }
}

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_PREAUTHORIZE_CANCEL)
`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
`referenceId`	String	1-50	Required	Reference ID for the transaction
`transactionId`	String	1-50	Required	Transaction ID
`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"
  }
}

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 Parameters: Includes details for the transaction cancelation request such as referenceId, transactionId, and description (e.g., cancelation description).
Response Parameters: Contains status information about the response, including the transaction state (approved), description, and transaction IDs.

3. 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 referenceId and transactionId.

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}},
    "referenceId": "{{referenceId}}",
    "transactionId": "{{transactionId}}",
    "description": "PREAUTH Commited"
  }
}

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_PREAUTHORIZE_COMMIT)
`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
`referenceId`	String	1-50	Required	Reference ID for the transaction
`transactionId`	String	1-50	Required	Transaction ID
`description`	String	0-255	Optional	Description of the action (e.g., "PREAUTH 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"
  }
}

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 committing the preauthorization, such as referenceId, transactionId, and a description of the action
Response Key Parameters: Contains the result of the commit action, including the state (approved), description, and transaction identifiers.

PreAuthorization

On this page