---
title: "Card Charge"
method: POST
path: "/card/card_charge/"
tags: ["Card Collection"]
---

# Card Charge

`POST /card/card_charge/`

This endpoint is used to initiate Card payments for merchants that use our platform. This document has various Request bodies and HTML text that are necessary for different integration purposes. See the full [Cards guide](/guides/card-collection) for a step-by-step walkthrough. 

**Note:**

- The Card Acquirer Response Codes with descriptions can be found <a href="https://docs.google.com/spreadsheets/d/13AmGYgpGxEVNMnTtvBYg_NZaHaBbcp9ZbSfzhR-1ft4/edit?usp=sharing" target="_blank">here</a>
- Please be advised that card collections to countries other than Nigeria are exclusively available upon request. To initiate this process, kindly send an email to <b>support@payaza.africa</b>. You will be granted access once our team reviews and approves your request.

## Request body

- CardChargeRequest
  - `service_payload` object, required
    - `first_name` string, required — The first name of the customer.
    - `last_name` string, required — The last name of the customer.
    - `email_address` string, email, required — The email address of the customer.
    - `phone_number` string, required — The phone number of the customer.
    - `amount` number, double, required — The amount to be charged.
    - `transaction_reference` string, required — The unique identifier given to a particular transaction. (Maximum character length is 15).
    - `currency` string, required — Currency code for the transaction. The base currency is NGN
    - `description` string, required — Description for the payment.
    - `card` object, required — The details of the card.
      - `expiryMonth` string, required — The month the card will expire.
      - `expiryYear` string, required — The year the card will expire
      - `securityCode` string, required — CVV/CVC code.
      - `cardNumber` string, required — The number on the card.
      - `pin` string — The PIN for the card. This is only required for NGN collections.
    - `callback_url` string, uri — The callback URL provided by the merchant (Kindly ensure this accepts POST requests).

## Response `200`

Card Charge Responses

- union
  - CardCharge3dsResponse
    - `statusOk` boolean — Indicates if the initial request was valid.
    - `message` string — Response message.
    - `debugMessage` string — Detailed debug message.
    - `descriptor` string — Payment descriptor (if available).
    - `waitForNotification` boolean — Whether the client should wait for a notification.
    - `do3dsAuth` boolean — Flag indicating that 3DS authentication is required.
    - `threeDsUrl` string, uri — The URL to which the 3DS challenge should be submitted.
    - `formData` string — Base64 encoded form data or payload for the 3DS request.
    - `threeDsHtml` string — Full HTML form required to auto-submit the 3DS challenge.
    - `paymentCompleted` boolean — Indicates if the payment is complete.
    - `amountPaid` number — Amount successfully paid so far.
    - `valueAmount` number — Total value amount processed.
  - CardChargeSuccessCallbackResponse
    - `statusOk` boolean — Indicates if the transaction was successful.
    - `message` string — Response message.
    - `debugMessage` string — Detailed debug message.
    - `description` string — Transaction narration.
    - `descriptor` string — Merchant descriptor.
    - `waitForNotification` boolean — Indicates if the client should wait for a webhook.
    - `transactionReference` string — Unique transaction reference.
    - `customerReference` string — Customer reference ID.
    - `do3dsAuth` boolean — Whether 3DS authentication was required.
    - `paymentCompleted` boolean — Indicates if the payment is complete.
    - `amountPaid` number, double — Total amount paid by the customer.
    - `valueAmount` number, double — Settlement value (amount credited).
    - `payer_name` string — Name of the cardholder.
    - `source_bank_name` string — Name of the issuing bank.
    - `payment_date` string — Timestamp of payment.
    - `created_at` string — Timestamp when the record was created.
    - `rrn` string — Retrieval Reference Number.
    - `risk` object — Risk assessment data.
    - `acquirer_response_code` string — Response code from the acquirer.
  - CardChargeFailedCallbackResponse
    - `statusOk` boolean — Indicates if the transaction was successful.
    - `message` string — User-friendly response message.
    - `debugMessage` string — Detailed reason for failure.
    - `description` string — Transaction narration.
    - `waitForNotification` boolean — Indicates if a webhook notification is expected.
    - `transactionReference` string — Unique transaction reference.
    - `do3dsAuth` boolean — Whether 3DS authentication was attempted.
    - `paymentCompleted` boolean — Indicates if funds were moved.
    - `amountPaid` number — Amount successfully charged (0 in failure cases).
    - `valueAmount` number — Settlement value.
    - `acquirer_response_code` string — Response code from the acquiring bank (empty if blocked by risk engine before reaching bank).
    - `risk` object — Risk assessment details.
      - `response` object
        - `gatewayCode` string — Risk gateway decision.
        - `totalScore` integer — Total risk score assigned (higher usually means higher risk).
        - `review` object
          - `decision` string
        - `rule` object[] — List of risk rules triggered.
          - `name` string — Name of the rule triggered.
          - `type` string — Type of rule (e.g., EXTERNAL_RULE, MSO_RULE).
          - `data` string — Specific data point associated with the rule (optional).
          - `recommendation` string — Recommended action for this specific rule (optional).

## Other responses

- `400` — Invalid request

---

[API](https://skmtc.net/payaza/apis/payaza-documentation.md) · [All operations](https://skmtc.net/payaza/apis/payaza-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/payaza/payaza-documentation/revisions/1ecd4b94ff07/schema)