> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payaza.africa/llms.txt
> Use this file to discover all available pages before exploring further.

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




## OpenAPI

````yaml /openapi.json post /card/card_charge/
openapi: 3.0.1
info:
  title: Payaza Documentation
  version: 2.0.0
  description: >-
    API reference for processing payments using Card, Bank Transfer, USSD, and
    QR Code methods.
servers:
  - url: https://api.payaza.africa/live
security:
  - ApiKeyAuth: []
  - TenantID: []
  - ProductID: []
tags:
  - name: Transfers
    description: >-
      Transfers are transactions made from your Payaza account to beneficiaries.
      Merchants can instantly transfer funds from their available balance. For
      every transfer, you need to specify the amount and the beneficiary’s
      details. You become eligible to make transfers after you have been
      verified. (you sign up, finish account activation and KYC verification).
  - name: Payaza Account
    description: >-
      This is our internal account that can be used to make payouts to other
      bank accounts, in single or in bulk. The Payaza account can also be used
      to receive settlements. It can also be used to track the transfer status
      of your transactions and check your balance instantly
  - name: Sub Accounts
    description: >-
      This enables you to establish Sub Payaza accounts for your customers. Each
      sub-account comes with an assigned static virtual account, facilitating
      direct funding for individual accounts. Furthermore, the Main Payaza
      account can directly initiate funding for each sub-account. These
      sub-accounts serve the purpose of managing unique account positions or
      balances and facilitating disbursements from these positions to specified
      beneficiaries.
  - name: EUR Accounts
    description: >-
      This endpoints enable you to create EUR subaccounts which can be used to
      make transfers as required .
  - name: Apple Pay and Google Pay
    description: >-
      Apple Pay and Google Pay give your customers a fast, familiar, and secure
      way to complete payments. Our APIs provide a gateway to provide these
      services to your users for a smooth payment experience.
  - name: Virtual Accounts
    description: >-
      Virtual Accounts are bank accounts that are created for a specific purpose
      and last for specified durations. Virtual accounts are issued by Payaza’s
      partner banks. Our virtual account APIs can be used to create virtual
      accounts and perform other tasks relevant to virtual accounts. Virtual
      accounts are created to foster easy payment collections for your business
      and platform. 

      Static/Reserved Account: This virtual account is created by the merchant
      and remains valid indefinitely. It can be used multiple times and does not
      expire. 

      Dynamic Account: This virtual account is generated for a specific
      transaction or purpose. Please note that dynamic virtual account remains
      valid for a temporary period of time or until a payment of the specified
      amount is received. Upon expiry, a merchant can generate another one for a
      different purpose.
  - name: Card Collection
    description: >-
      The Card Collection APIs can be used to make card transactions, refund
      transactions that have been performed, check the status of a transaction
      and so much more.
  - name: Card Tokenisation
    description: >-
      The Card Tokenisation APIs are used to create card tokens, charge cards
      using tokens, retrieve all tokens created by a merchant account and
      deleting any card token as desired.
  - name: Refunds And Chargebacks
    description: >-
      The Refunds and Chargeback APIs are used to initiate refunds, view your
      refund and chargeback history and so much more.
  - name: Branches
    description: >-
      The Refunds and Chargeback APIs are used to initiate refunds, view your
      refund and chargeback history and so much more.
  - name: Auth-Capture-Void
    description: >-
      The Auth-Capture-Void APIs provide a two-phase payment process where
      transactions are first authorized, then captured or voided. This allows
      merchants to hold funds and complete the transaction in the future.
  - name: Momo and ZAR Collections
    description: APIs for MoMo, ZAR and XOF collections.
  - name: Check Transaction Status(Merchant Reference)
    description: >-
      This endpoint is used to check the transaction status of a transaction
      using the Merchant Reference..
paths:
  /card/card_charge/:
    post:
      tags:
        - Card Collection
      summary: Card Charge
      description: >
        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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/cardChargeRequest'
            examples:
              Card Charge Request:
                summary: Card Charge Request
                value:
                  service_payload:
                    first_name: John
                    last_name: Doe
                    email_address: johndoe@hotmail.com
                    phone_number: '0939344401'
                    amount: 0.01
                    transaction_reference: T13501973673737
                    currency: USD
                    description: TEST
                    card:
                      expiryMonth: '10'
                      expiryYear: '26'
                      securityCode: '686'
                      cardNumber: '4865550017193640'
                    callback_url: https://calbackurl.com
      responses:
        '200':
          description: Card Charge Responses
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/cardCharge3dsResponse'
                  - $ref: '#/components/schemas/cardChargeSuccessCallbackResponse'
                  - $ref: '#/components/schemas/cardChargeFailedCallbackResponse'
              examples:
                Non-3DS Response:
                  summary: Non-3DS Response
                  value:
                    response_code: 200
                    response_message: Operation Completed
                    response_content:
                      statusOk: true
                      message: Approved
                      debugMessage: Transaction Successful
                      description: Test
                      descriptor: ' '
                      waitForNotification: true
                      transactionReference: 450Q03ed3dd613
                      customerReference: 450Q03ed3dd613
                      do3dsAuth: false
                      paymentCompleted: true
                      amountPaid: 0.01
                      valueAmount: 0.0095
                      rrn: '123456789012'
                      risk: {}
                      acquirer_response_code: '00'
                    status: '00'
                3DS Response:
                  summary: 3DS Response
                  value:
                    statusOk: true
                    message: Authentication Required
                    debugMessage: 3DS Authentication Required
                    descriptor: ''
                    waitForNotification: false
                    do3dsAuth: true
                    threeDsUrl: >-
                      https://secure-acs2ui-bk2-indmum-mumrdc.wibmo.com/v1/acs/services/browser/creq/L/8642/f701e19d-3508-11ee-b753-67cae4cf81dc
                    formData: >-
                      eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjQ5ZGJmNTY4LWRjZjUtNDc1NS05ZjQ2LWU2MjIzMDk3MGU3MyIsImFjc1RyYW5zSUQiOiJmNzAxZTE5ZC0zNTA4LTExZWUtYjc1My02N2NhZTRjZjgxZGMiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIn0
                    threeDsHtml: >-
                      <div id='threedsChallengeRedirect'
                      xmlns='http://www.w3.org/1999/html' style=' height:
                      100vh'> <form id ='threedsChallengeRedirectForm'
                      method='POST' action='https:
                      //secure-acs2ui-bk2-indmum-mumrdc.wibmo.com/v1/acs/services/browser/creq/L/8642/f701e19d-3508-11ee-b753-67cae4cf81dc'
                      target='challengeFrame'> <input type='hidden' name='creq'
                      value='eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjQ5ZGJmNTY4LWRjZjUtNDc1NS05ZjQ2LWU2MjIzMDk3MGU3MyIsImFjc1RyYW5zSUQiOiJmNzAxZTE5ZC0zNTA4LTExZWUtYjc1My02N2NhZTRjZjgxZGMiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIn0'
                      /> </form> <iframe id='challengeFrame'
                      name='challengeFrame' width='100%' height='100%'
                      ></iframe><script id='authenticate-payer-script'> var
                      e=document.getElementById('threedsChallengeRedirectForm');
                      if (e) { e.submit(); if (e.parentNode !== null) {
                      e.parentNode.removeChild(e);            }        }
                      </script> </div>
                    paymentCompleted: false
                    amountPaid: 0
                    valueAmount: 0
                Successful Callback Response:
                  summary: Succesful Callback Response
                  value:
                    statusOk: true
                    message: Approved
                    debugMessage: Transaction Successful
                    description: Test for 3DS
                    descriptor: ' '
                    waitForNotification: true
                    transactionReference: P1KRDXCD5630
                    customerReference: P1KRDXCD5630
                    do3dsAuth: false
                    paymentCompleted: true
                    amountPaid: 24
                    valueAmount: 23.664
                    payer_name: John Doe
                    source_bank_name: VISA
                    payment_date: 2024-03-11+19:49:43.575475932
                    created_at: 2024-03-11+19:49:43.575475932
                    rrn: '519219078440'
                    risk: {}
                    acquirer_response_code: '00'
                Failed Callback Response:
                  summary: Failed Callback Response
                  value:
                    statusOk: false
                    message: Transaction Failed
                    debugMessage: BLOCKED
                    description: Test for 3DS
                    waitForNotification: false
                    transactionReference: PL-1KBPSCJCR2015021
                    do3dsAuth: false
                    paymentCompleted: false
                    amountPaid: 0
                    valueAmount: 0
                    risk:
                      response:
                        gatewayCode: REJECTED
                        review:
                          decision: NOT_REQUIRED
                        rule:
                          - name: 3D Secure Passed
                            type: EXTERNAL_RULE
                          - name: 'AI: Average spend on this card in the last 30 days'
                            type: EXTERNAL_RULE
                          - name: >-
                              AI: No. of transactions with the card 10-40 days
                              before this
                            type: EXTERNAL_RULE
                          - name: 'AI: Total spend on the card 10-40 days before this'
                            type: EXTERNAL_RULE
                          - name: >-
                              AI: Total spend, same card and merchant 10-40 days
                              before this
                            type: EXTERNAL_RULE
                          - name: 'AI: mer_city'
                            type: EXTERNAL_RULE
                          - name: >-
                              Cards to IP address - Multiple cards associated to
                              the same IP address
                            type: EXTERNAL_RULE
                          - name: Distinct card names to card
                            type: EXTERNAL_RULE
                          - name: Distinct card names to card high
                            type: EXTERNAL_RULE
                          - name: Distinct cards to IP address
                            type: EXTERNAL_RULE
                          - data: NO_RULES
                            name: MSO_3D_SECURE
                            recommendation: NO_ACTION
                            type: MSO_RULE
                          - data: '539983'
                            name: MSO_BIN_RANGE
                            recommendation: NO_ACTION
                            type: MSO_RULE
                          - data: 127.0.0.1
                            name: MSO_IP_ADDRESS_RANGE
                            recommendation: NO_ACTION
                            type: MSO_RULE
                          - data: UK1
                            name: MSO_IP_COUNTRY
                            recommendation: NO_ACTION
                            type: MSO_RULE
                        totalScore: 100
                    acquirer_response_code: ''
        '400':
          description: Invalid request
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: 3DS Authentication HTMl
          label: 3DS Authentication HTML
          source: |-
            <body>
                <div id='threedsChallengeRedirect' xmlns='http://www.w3.org/1999/html' style=' height: 100vh'>
                    <form id='threedsChallengeRedirectForm' method='POST' action='' target='challengeFrame'>
                        <input type='hidden' name='creq' id="creq" value=''/>
                    </form>
                    <iframe id='challengeFrame' name='challengeFrame' width='100%' height='100%'></iframe>
                </div>

                <script>
                    const cardNumber = "4187451844054629"; // Card Number
                    const expiryMonth = "07"; // Card Expiry Month
                    const expiryYear = "32"; // Card Expiry Year
                    const securityCode = "100"; // Card Security Code
                    //const pin = "1000"// Card PIN //For NGN cards


                    var myHeaders = new Headers();
                    myHeaders.append("Authorization", "Payaza UFo3OC1QS0xJhsksksMjFFNEYtQ0VCNy00MjAzL4MDktQkU1NEM3NDY1RDRB");
                    myHeaders.append("Content-Type", "application/json");

                    var raw = JSON.stringify({
                        "service_type": "Account",
                        "service_payload": {
                            "first_name": "John",
                            "last_name": "Doe",
                            "email_address": "johndoe@email.com",
                            "phone_number": "090121980906",
                            "amount": 11,
                            "transaction_reference": "PL-1KBPSCJCR" + Math.floor(
                                (Math.random() * 10000000) + 1
                            ),
                            "currency": "NGN",
                            "description": "Test for 3DS",
                            "card": {
                                "expiryMonth": expiryMonth,
                                "expiryYear": expiryYear,
                                "securityCode": securityCode,
                                "cardNumber": cardNumber,
                                //"pin": pin //For NGN cards

                            }
                        }
                    });

                    var requestOptions = {
                        method: 'POST',
                        headers: myHeaders,
                        body: raw,
                        redirect: 'follow'
                    };

                    fetch("https://api.payaza.africa/live/card/card_charge/", requestOptions).then(response => response.text()).then(result => {
                        result = JSON.parse(result);
                        if (result.statusOk) { // ///Handle Success Response
                            const creq = document.getElementById("creq");
                            creq.value = result.formData;
                            const form = document.getElementById("threedsChallengeRedirectForm");
                            form.setAttribute("action", result.threeDsUrl);
                            form.submit();
                        } else { // ///Handle Error
                            console.log("Error found", result.debugMessage)
                            alert("Payment Failed: " + result.debugMessage)
                        }
                    }).catch(error => {
                        console.log("Error", error)
                        alert("Exception Error: " + error.debugMessage)
                    });



                    / ///////////Internal Payment Notification
                    window.addEventListener("message", (event) => {
                        console.log("::::::::::::::::::MESSAGE EVENT GOT BACK FROM BACK-END::::::::::::::::::::::")
                        try{
                            const response = JSON.parse(event.data);
                            console.log("Payment Notification", response)
                            if (response.statusOk !== undefined) {
                                if (response.statusOk === true && response.paymentCompleted === true) { // ////Handle payment successful, do business logic
                                    alert("Payment Successful")
                                } else { // ///Handle Failed payment
                                    alert("Payment Failed")
                                }
                            }
                        }catch(error){
                            console.log("Error from Parsing JSON",error)
                        }
                    });

                </script>
            </body>
components:
  schemas:
    cardChargeRequest:
      title: Card Charge Request
      type: object
      required:
        - service_payload
      properties:
        service_payload:
          type: object
          description: ''
          required:
            - first_name
            - last_name
            - email_address
            - phone_number
            - amount
            - transaction_reference
            - currency
            - description
            - card
          properties:
            first_name:
              type: string
              description: The first name of the customer.
              example: John
            last_name:
              type: string
              description: The last name of the customer.
              example: Doe
            email_address:
              type: string
              format: email
              description: The email address of the customer.
              example: johndoe@hotmail.com
            phone_number:
              type: string
              description: The phone number of the customer.
              example: '0939344401'
            amount:
              type: number
              format: double
              description: The amount to be charged.
              example: 0.01
            transaction_reference:
              type: string
              description: >-
                The unique identifier given to a particular transaction. 
                (Maximum character length is 15).
              example: T13501973673737
            currency:
              type: string
              description: Currency code for the transaction. The base currency is NGN
              example: USD
            description:
              type: string
              description: Description for the payment.
              example: TEST
            card:
              type: object
              description: The details of the card.
              required:
                - expiryMonth
                - expiryYear
                - securityCode
                - cardNumber
              properties:
                expiryMonth:
                  type: string
                  description: The month the card will expire.
                  example: '10'
                expiryYear:
                  type: string
                  description: The year the card will expire
                  example: '26'
                securityCode:
                  type: string
                  description: CVV/CVC code.
                  example: '686'
                cardNumber:
                  type: string
                  description: The number on the card.
                  example: '4865550017193640'
                pin:
                  type: string
                  description: >-
                    The PIN for the card. This is only required for NGN
                    collections.
                  example: '1234'
            callback_url:
              type: string
              format: uri
              description: >-
                The callback URL provided by the merchant (Kindly ensure this
                accepts POST requests).
              example: https://callbackurl.com
    cardCharge3dsResponse:
      title: Card Charge 3DS Response
      type: object
      properties:
        statusOk:
          type: boolean
          description: Indicates if the initial request was valid.
          example: true
        message:
          type: string
          description: Response message.
          example: Authentication Required
        debugMessage:
          type: string
          description: Detailed debug message.
          example: 3DS Authentication Required
        descriptor:
          type: string
          description: Payment descriptor (if available).
          example: ''
        waitForNotification:
          type: boolean
          description: Whether the client should wait for a notification.
          example: false
        do3dsAuth:
          type: boolean
          description: Flag indicating that 3DS authentication is required.
          example: true
        threeDsUrl:
          type: string
          format: uri
          description: The URL to which the 3DS challenge should be submitted.
          example: ''
        formData:
          type: string
          description: Base64 encoded form data or payload for the 3DS request.
          example: eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjQ5ZGJ...
        threeDsHtml:
          type: string
          description: Full HTML form required to auto-submit the 3DS challenge.
          example: <div id='threedsChallengeRedirect'> ... </div>
        paymentCompleted:
          type: boolean
          description: Indicates if the payment is complete.
          example: false
        amountPaid:
          type: number
          description: Amount successfully paid so far.
          example: 0
        valueAmount:
          type: number
          description: Total value amount processed.
          example: 0
    cardChargeSuccessCallbackResponse:
      title: Card Charge Successful Callback Response
      type: object
      properties:
        statusOk:
          type: boolean
          description: Indicates if the transaction was successful.
          example: true
        message:
          type: string
          description: Response message.
          example: Approved
        debugMessage:
          type: string
          description: Detailed debug message.
          example: Transaction Successful
        description:
          type: string
          description: Transaction narration.
          example: Test for 3DS
        descriptor:
          type: string
          description: Merchant descriptor.
          example: ' '
        waitForNotification:
          type: boolean
          description: Indicates if the client should wait for a webhook.
          example: true
        transactionReference:
          type: string
          description: Unique transaction reference.
          example: P1KRDXCD5630
        customerReference:
          type: string
          description: Customer reference ID.
          example: P1KRDXCD5630
        do3dsAuth:
          type: boolean
          description: Whether 3DS authentication was required.
          example: false
        paymentCompleted:
          type: boolean
          description: Indicates if the payment is complete.
          example: true
        amountPaid:
          type: number
          format: double
          description: Total amount paid by the customer.
          example: 24
        valueAmount:
          type: number
          format: double
          description: Settlement value (amount credited).
          example: 23.664
        payer_name:
          type: string
          description: Name of the cardholder.
          example: John Doe
        source_bank_name:
          type: string
          description: Name of the issuing bank.
          example: VISA
        payment_date:
          type: string
          description: Timestamp of payment.
          example: 2024-03-11+19:49:43.575475932
        created_at:
          type: string
          description: Timestamp when the record was created.
          example: 2024-03-11+19:49:43.575475932
        rrn:
          type: string
          description: Retrieval Reference Number.
          example: '519219078440'
        risk:
          type: object
          description: Risk assessment data.
          example: {}
        acquirer_response_code:
          type: string
          description: Response code from the acquirer.
          example: '00'
    cardChargeFailedCallbackResponse:
      title: Card Charge Failed Callback Response
      type: object
      properties:
        statusOk:
          type: boolean
          description: Indicates if the transaction was successful.
          example: false
        message:
          type: string
          description: User-friendly response message.
          example: Transaction Failed
        debugMessage:
          type: string
          description: Detailed reason for failure.
          example: BLOCKED
        description:
          type: string
          description: Transaction narration.
          example: Test for 3DS
        waitForNotification:
          type: boolean
          description: Indicates if a webhook notification is expected.
          example: false
        transactionReference:
          type: string
          description: Unique transaction reference.
          example: PL-1KBPSCJCR2015021
        do3dsAuth:
          type: boolean
          description: Whether 3DS authentication was attempted.
          example: false
        paymentCompleted:
          type: boolean
          description: Indicates if funds were moved.
          example: false
        amountPaid:
          type: number
          description: Amount successfully charged (0 in failure cases).
          example: 0
        valueAmount:
          type: number
          description: Settlement value.
          example: 0
        acquirer_response_code:
          type: string
          description: >-
            Response code from the acquiring bank (empty if blocked by risk
            engine before reaching bank).
          example: ''
        risk:
          type: object
          description: Risk assessment details.
          properties:
            response:
              type: object
              properties:
                gatewayCode:
                  type: string
                  description: Risk gateway decision.
                  example: REJECTED
                totalScore:
                  type: integer
                  description: >-
                    Total risk score assigned (higher usually means higher
                    risk).
                  example: 100
                review:
                  type: object
                  properties:
                    decision:
                      type: string
                      example: NOT_REQUIRED
                rule:
                  type: array
                  description: List of risk rules triggered.
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Name of the rule triggered.
                        example: 3D Secure Passed
                      type:
                        type: string
                        description: Type of rule (e.g., EXTERNAL_RULE, MSO_RULE).
                        example: EXTERNAL_RULE
                      data:
                        type: string
                        description: >-
                          Specific data point associated with the rule
                          (optional).
                        example: 127.0.0.1
                      recommendation:
                        type: string
                        description: Recommended action for this specific rule (optional).
                        example: NO_ACTION
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Payaza {{Public API Key in Base 64}}
    TenantID:
      type: apiKey
      in: header
      name: X-TenantID
      description: live or test
    ProductID:
      type: apiKey
      in: header
      name: X-ProductID
      description: 'default value is ‟app” '

````