payments & payouts

Time	Status	User Agent
Retrieving recent requests…

Request Body

Top-level fields

Field	Type	Required	Description
`request_type`	string	Yes	`"payment"` or `"payout"`. Determines which sub-fields are required below.
`reference`	string	Yes	Your unique merchant reference for this transaction. Use it later for status queries and webhook deduplication.
`amount`	number	Yes	Amount in minor currency units (e.g., kobo for NGN, cents for USD). Must be greater than 0.
`currency`	string	Yes	ISO 4217 currency code (e.g., `"NGN"`, `"USD"`).
`payment_method`	string	Yes when `request_type="payment"`	`"card"` or `"virtual_account"`. Omit for payouts.
`payment_method_id`	string	Yes when `payment_method="virtual_account"`	Identifier of the virtual account configuration to use.
`expiry_duration`	integer	Yes when `payment_method="virtual_account"`	How long the virtual account stays open, in seconds. Minimum `60`.
`source`	object	Yes when `payment_method="card"`	Card details — see `source` below.
`customer`	object	Conditional	Customer info — see `customer` below. Required for payouts.
`3ds`	object	Optional	3-D Secure configuration for card payments — see `3ds` below.
`redirect_url`	string	Yes for card payments	URL we redirect the payer to after 3DS / authentication.
`narration`	string	Optional	Free-text description of the transaction.
`payment_ip`	string	Optional	Payer's IP address (helps with fraud scoring).
`authorization_type`	string	Optional	Reserved for future use (e.g., recurring authorizations).
`capture`	boolean	Optional	When `false`, authorize only without capturing. Defaults to `true`.
expiry_duration	integer (seconds)	Optional when payment_method=virtual_account	How long the account stays open to receive funds. Minimum 60.

`source` object (card payments)

Field	Type	Required	Description
`type`	string	Yes	Always `"card"`.
`pan`	string	Yes	The card number (PAN). Must pass standard credit card validation.
`name`	string	Yes	Cardholder name as it appears on the card.
`expiry_month`	string	Yes	Two-digit expiry month, e.g. `"09"`.
`expiry_year`	string	Yes	Four-digit expiry year, e.g. `"2028"`.
`cvv`	string	Yes	3- or 4-digit card verification value.
`billing_address.address_line1`	string	Optional	Street address line 1.
`billing_address.address_line2`	string	Optional	Street address line 2.
`billing_address.city`	string	Optional	City.
`billing_address.state`	string	Optional	State or region.
`billing_address.postal_code`	string	Optional	ZIP / postal code.
`billing_address.country`	string	Optional	ISO 3-letter country code (e.g. `"NGA"`).

`customer` object

For card payments, the customer block is optional but recommended (any one of name / email requires reference). For payouts, account_number, bank_code, and name are required.

Field	Type	Required	Description
`reference`	string	Conditional	Your reference for the customer. Required if `name` or `email` is set.
`name`	string	Conditional	Customer's full name. Required for payouts.
`email`	string	Conditional	Customer's email. Required if `reference` is set.
`account_number`	string	Yes for payouts	Beneficiary bank account number — exactly 10 digits.
`bank_code`	string	Yes for payouts	Beneficiary bank code. Use `GET /api/banks` to enumerate valid codes.

`3ds` object (card payments only)

Field	Type	Required	Description
`enabled`	boolean	Optional	Set `true` to enable 3-D Secure authentication.
`challenge_preference`	string	Optional	One of `"challenge_mandated"`, `"challenge_preferred"`, `"no_preference"`, `"no_challenge"`.

Example Requests

Card payment with 3DS

{
  "request_type": "payment",
  "payment_method": "card",
  "reference": "ORD-2026-00482",
  "amount": 250000,
  "currency": "NGN",
  "narration": "Order #ORD-2026-00482",
  "redirect_url": "https://merchant.example/checkout/return",
  "payment_ip": "102.89.45.12",
  "source": {
    "type": "card",
    "pan": "4242424242424242",
    "name": "Jane Doe",
    "expiry_month": "09",
    "expiry_year": "2028",
    "cvv": "123",
    "billing_address": {
      "address_line1": "12 Marina Road",
      "city": "Lagos",
      "state": "Lagos",
      "postal_code": "101241",
      "country": "NGA"
    }
  },
  "customer": {
    "reference": "CUST-9381",
    "name": "Jane Doe",
    "email": "[email protected]"
  },
  "3ds": {
    "enabled": true,
    "challenge_preference": "challenge_preferred"
  }
}

Virtual account payment

{
  "request_type": "payment",
  "payment_method": "virtual_account",
  "payment_method_id": "va-cfg-78a2",
  "expiry_duration": 1800,
  "reference": "ORD-2026-00483",
  "amount": 500000,
  "currency": "NGN",
  "narration": "Invoice INV-2226",
  "customer": {
    "reference": "CUST-9381",
    "name": "Jane Doe",
    "email": "[email protected]"
  }
}

Payout to a bank account

{
  "request_type": "payout",
  "reference": "PO-2026-00112",
  "amount": 1500000,
  "currency": "NGN",
  "narration": "Vendor payment — May invoice",
  "customer": {
    "name": "Acme Suppliers Ltd",
    "account_number": "0123456789",
    "bank_code": "058"
  }
}

Response Body

The same PaymentResponse shape is returned for all three request flows — fields not relevant to the chosen flow are simply omitted.

Top-level fields

Field	Type	Description
`request_type`	string	Echoes the request type (`"payment"` or `"payout"`).
`id`	string (UUID)	The Payline transaction ID.
`reference`	string	Your merchant reference.
`payment_link_id`	string	Payment link ID, if the payment was created from a link.
`status`	string	Transaction status — see PaymentTransactionStatus.
`refund_status`	string	Refund state — see PaymentRefundStatus.
`settle_status`	string	Settlement state — see PaymentSettlementStatus.
`virtual_account_details`	object	Populated only when `payment_method = "virtual_account"`. See `virtual_account_details` below.
`response_code`	string	Numeric internal code summarising the outcome (e.g. `"10000"` for success).
`response_summary`	string	Human-readable explanation (e.g. `"Payment completed"`).
`gateway_code`	string	Acquirer / gateway response code (e.g. `"APPROVED"`).
`gateway_recommendation`	string	Acquirer recommendation (e.g. retry, do not retry).
`retrieval_reference_number`	string	RRN from the acquirer.
`system_trace_audit_number`	string	STAN from the acquirer.
`acquirer_transaction_id`	string	Acquirer's transaction identifier.
`authorization_code`	string	Authorization code returned by the card issuer.
`merchant_descriptor`	string	Descriptor that will appear on the cardholder's statement.
`amount`	number	Transaction amount in minor units.
`fee`	number	Processing fee charged in minor units.
`currency`	string	ISO 4217 currency code.
`payment_timestamp`	string (RFC 3339)	When the transaction was created server-side.
`redirect_link`	string	For card payments requiring 3DS — redirect the payer here.
`source`	object	Card details echoed back — see `source` below.
`customer`	object	Customer details — see `customer` below.
`total_amount_captured`	number	Cumulative amount captured for this transaction.
`total_amount_available_to_refund`	number	Refundable balance remaining.
`total_amount_refunded`	number	Cumulative amount already refunded.

`source` (in response)

Field	Type	Description
`type`	string	Always `"card"` for card payments.
`card_type`	string	Card brand — e.g. `"VISA"`, `"MASTERCARD"`, `"VERVE"`.
`card_bin`	string	First 6 digits of the PAN.
`card_last4`	string	Last 4 digits of the PAN.
`expiry_month`	string	Two-digit expiry month.
`expiry_year`	string	Four-digit expiry year.

`customer` (in response)

Field	Type	Description
`name`	string	Customer / beneficiary name.
`account_number`	string	Beneficiary account number (payouts).
`bank_code`	string	Beneficiary bank code (payouts).
`bank_name`	string	Beneficiary bank name (payouts).
`merchant_reference`	string	Your reference for the customer (if you supplied one).

`virtual_account_details` (virtual account payments)

Field	Type	Description
`account_number`	string	The bank account number the payer should transfer to.
`bank`	string	Bank name hosting the virtual account.
`account_name`	string	Name printed on the virtual account.
`expected_amount`	string	Amount the payer is expected to send (matches request `amount`).
`amount_received`	string	Amount actually received. Empty until the transfer arrives.
`expires_at`	string (RFC 3339)	When this virtual account stops accepting funds.
`status`	string	One of `"pending"`, `"success"`, `"mismatch"`, `"expired"`, `"failed"`.

Status Enums

`status` — PaymentTransactionStatus

Value	Meaning
`pending`	Transaction created; awaiting payment or authorization.
`success`	Transaction completed successfully.
`failed`	Transaction terminally failed.

`refund_status` — PaymentRefundStatus

Value	Meaning
`none`	No refund attempted.
`partially_refunded`	Some, but not all, of the amount has been refunded.
`refunded`	Full amount refunded.
`refund_failed`	A refund attempt failed.

`settle_status` — PaymentSettlementStatus

Value	Meaning
`initiated`	Settlement batch created.
`pending`	Awaiting bank processing.
`rejected`	Settlement rejected by the bank.
`approved`	Approved; funds awaiting release.
`released`	Funds released to the merchant wallet.

Example Responses

Card payment (3DS pending — payer must complete redirect)

{
  "request_type": "payment",
  "id": "9f8a4bb1-7d2c-4f9d-9e2d-a3b6c0a18a55",
  "reference": "ORD-2026-00482",
  "status": "pending",
  "refund_status": "none",
  "response_code": "10001",
  "response_summary": "Processing",
  "amount": 250000,
  "fee": 1250,
  "currency": "NGN",
  "payment_timestamp": "2026-05-19T10:30:00Z",
  "redirect_link": "https://checkout.payline.co/3ds/eyJhbGciOi…",
  "source": {
    "type": "card",
    "card_type": "VISA",
    "card_bin": "424242",
    "card_last4": "4242",
    "expiry_month": "09",
    "expiry_year": "2028"
  },
  "customer": {
    "name": "Jane Doe",
    "merchant_reference": "CUST-9381"
  }
}

Virtual account payment

{
  "request_type": "payment",
  "id": "f1c2d3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a",
  "reference": "ORD-2026-00483",
  "status": "pending",
  "response_code": "10001",
  "response_summary": "Processing",
  "amount": 500000,
  "currency": "NGN",
  "payment_timestamp": "2026-05-19T10:32:11Z",
  "virtual_account_details": {
    "account_number": "9988776655",
    "bank": "Providus",
    "account_name": "PAYLINE/ORD-2026-00483",
    "expected_amount": "500000",
    "expires_at": "2026-05-19T11:02:11Z",
    "status": "pending"
  },
  "customer": {
    "name": "Jane Doe",
    "merchant_reference": "CUST-9381"
  }
}

Payout

{
  "request_type": "payout",
  "id": "a0b1c2d3-e4f5-6789-abcd-ef0123456789",
  "reference": "PO-2026-00112",
  "status": "success",
  "response_code": "10000",
  "response_summary": "Payment completed",
  "amount": 1500000,
  "fee": 50000,
  "currency": "NGN",
  "payment_timestamp": "2026-05-19T10:35:48Z",
  "customer": {
    "name": "Acme Suppliers Ltd",
    "account_number": "0123456789",
    "bank_code": "058",
    "bank_name": "GTBank"
  }
}

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., "sktest$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.

Request Body

Top-level fields

source object (card payments)

customer object

3ds object (card payments only)

Example Requests

Card payment with 3DS

Virtual account payment

Payout to a bank account

Response Body

Top-level fields

source (in response)

customer (in response)

virtual_account_details (virtual account payments)

Status Enums

status — PaymentTransactionStatus

refund_status — PaymentRefundStatus

settle_status — PaymentSettlementStatus

Example Responses

Card payment (3DS pending — payer must complete redirect)

Virtual account payment

Payout

Verify Card Payload

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:

200Successfully initiated the payment

400Bad Request: Invalid request payload

500Internal Server Error

`source` object (card payments)

`customer` object

`3ds` object (card payments only)

`source` (in response)

`customer` (in response)

`virtual_account_details` (virtual account payments)

`status` — PaymentTransactionStatus

`refund_status` — PaymentRefundStatus

`settle_status` — PaymentSettlementStatus