payments & payouts

POST https://api-staging.co/api/payments

This endpoint either initiates a new payment process or performs a card verification check. The operation is determined by the payment details included in the request.

Initiate Payment Process

key	type	description
request_type	string	charge/card_check/refund/payout
reference	string	Reference identifier for the payment.
currency	string	Currency used for the payment.
source	object	name: NameOnCard pan: CardNumber cvv: CVV expiry_month: ExpireMonth expiry_year: ExpireYear type: CARD "billing_address": { "address_line1": "The primary street address (e.g., house number and street name)", "address_line2": "The secondary address line (e.g., apartment or suite number, optional)", "city": "The city name for the billing address", "country": "Valid alpha-3 code for the country (ISO 3166-1 standard)", "postal_code": "The postal or ZIP code for the billing address", "state": "The state, province, or region for the billing address" } Payout: account
customer	object	reference: CustomerReference name: CustomerName email: CustomerEmail account_number: Customer Account Number (payout) bank_code: Customer bank code (/banks endpoint)
amount	number	Total amount of the payment.
payment_type	string	Type of payment to be initiated
capture	boolean	true or false (true)
authorization_type	string	Authorization type for payment (final)
3ds	object	enabled:To enable or disable 3DS challenge_preference: 3DS challenge reference
redirect_url	string	redirect URL
narration	string	transaction narration

Payment Response

key	type	description
id	string	Unique identifier for the payment.
reference	string	Reference identifier for the payment.
amount	number	Total amount of the payment.
currency	string	Currency used for the payment.
fee	number	Transaction fee applied to the payment.
payment_timestamp	string	Timestamp when the payment was processed.
redirect_link	string	Link to redirect the user, if applicable.
request_type	string	Type of the payment request (charge, card_check, refund).
response_summary	string	Summary of the payment response.
status	string	Current status of the payment (pending, success, failed).
settle_status	string	Payment settlement status (initiated, pending, released)

Verify Card Payload

key	type	description
request_type	string	card_check
currency	string	Currency used for the payment.
source	object	name: NameOnCard pan: CardNumber cvv: CVV expiry_month: ExpireMonth expiry_year: ExpireYear type: CARD

---

Generating the X-Signature

📘

To securely authenticate API requests, a signature (X-Signature) must be generated and included in the request headers. This signature is a HMAC SHA256 hash of the request data, using a provided secret key.

Steps to Generate the X-Signature:

• Prepare the Data: The data to be sent in the API request (request payload) should be prepared as a string.
• Generate HMAC SHA256 Signature (e.g using crypto-js for Node:
  • Use the HMAC SHA256 algorithm on the request data string.
  • The secret key for HMAC SHA256 is provided (e.g., "sk_test_$jmrluwtudhbztd@s&lu").
  • The output should be converted to a hexadecimal string.
    **Include the Signature in Headers: **The resulting hexadecimal string is used as the value for the X-Signature header in the API request.