Cards

Initiate a card payment.

Initialization

POST /payment-sessions

To initialize the transaction, you need to pass information such as user, amount, transaction reference, etc. The snippet below outlines the parameters you can use when initializing a transaction.

Request Param	Description	Data type	Required?
amount	Amount to charge; should be in Kobo and cents if payment method is not binance pay. For binance pay, it should be in actual USD value. identifier of the user you wish to charge; required if you've passed the user for a charge previously.	integer	Yes
customer	user for whom the payment is being charged.	object	Yes
description	description of the payment transaction.	string	Yes
currency	the currency you wish to charge the user. NGN, USD	string	Yes
amount	The amount to charge; should be in Kobo and cents if the payment method is not Binance pay. For Binance pay, it should be in actual USD value. minimum: 100000	integer	Yes
direction	The direction of payment; defaults to incoming	string	Yes
payment_method	payment method object. [ bank_account, card, wallet, crypto_address ]	object	No
settlement_target	defaults to business.	string	No
metadata	Metadata for the transaction.	object	Yes

Sample request to initialize a card payment

{
    "customer": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[e-mail]",
        "phone_number": "[phone]",
        "billing_address": {
            "line1": "123 Main St",
            "line2": "456 main ext",
            "city": "Springfield",
            "state": "CA",
            "country": "US",
            "zip_code": "12345"
        }
    },
    "customer_id": "existing customer id", // mutually-exclusive with the customer field
    "description": "Test",
    "currency": "NGN | USD | CAD",
    "amount": 100000,
    "direction": "incoming",
    "payment_method": {
        "type": "card"
    },
    "reference": "1b09d9b2-11jd9eheveb-9203v02g",
    "metadata": {
        "order": {
            "identifier": "ORD12345",
            "items": [
                {
                    "name": "Deposit",
                    "type": "digital"
                }
            ]
        }
    }
}

Sample Response after initializing a card payment

Code	Description
201	Payment session created
400	Request was invalid
422	Request contained validation errors

{
  "data": {
    "auth_type": "3ds",
    "expires_at": "2024-03-01T08:43:08.110470Z",
    "links": {},
    "message": "Created",
    "payment": {
      "amount": 50000,
      "cancellation_reason": "",
      "currency": "NGN",
      "customer": {
        "billing_address": {
          "city": "Awolowo Road",
          "country": "NG",
          "line1": "Opposite Sasa Estate",
          "line2": "123 Sofur street",
          "state": "Kwara",
          "zip_code": "23401"
        },
        "email": "[e-mail]",
        "first_name": "Enitan",
        "id": "d05e51df-809e-498a-ac3f-7acfc0b5d35d",
        "last_name": "Michael",
        "phone_number": "[phone]"
      },
      "date": "2024-02-29T20:43:08.344264Z",
      "description": "Deposit",
      "id": "2549c96c-d743-11ee-aa4d-c6d49632367b",
      "metadata": {
        "order": {
          "identifier": "juice-deposit-dbf99bd0-262a-46bd-8339-3c741d040dbb",
          "items": [
            {
              "name": "Deposit",
              "type": "digital"
            }
          ]
        }
      },
      "mode": "live",
      "payment_method": {
        "card_number": "417396******9621",
        "expiry_month": 6,
        "expiry_year": 2024,
        "id": "5e21efda-c526-4057-92f6-1b94ee210b47",
        "type": "card"
      },
      "reference": "ref-juice-85d53ab5-92b8-4151-9f8f-a4f12863a911",
      "status": "pending"
    },
    "status": "pending"
  }
}