Skip to main content
Card payments may require more than one API call before Payfonte can confirm the final outcome. The first card request returns an action that tells your backend what to collect or do next.

​
Endpoints

MethodEndpointPurpose
POST/payments/v1/cards/processSubmit card details and start the card payment
POST/payments/v1/cards/pinSubmit card PIN when the response action is pin
POST/payments/v1/cards/otpSubmit customer OTP when the response action is otp
GET/payments/v1/payments/verify/{reference}Verify final transaction status when the response action is verification

​
Testing

Sandbox card test data is available in Testing.

​
Integration Steps

1

Submit card details

Call /payments/v1/cards/process with provider, amount, and card. Send your client identifier in the client-id header.
2

Read the action

Use data.action to decide whether to collect PIN, collect OTP, redirect for 3DS, or verify the payment.
3

Continue the required step

Submit PIN or OTP when requested, or redirect the customer to data.data.redirectURL for 3DS authentication.
4

Confirm final status

When the action is verification, call GET /payments/v1/payments/verify/{reference} from your backend before fulfilling the order.

​
Submit Card Details

curl --request POST \
  --url https://sandbox-api.payfonte.com/payments/v1/cards/process \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>' \
  --header 'content-type: application/json' \
  --data '{
    "provider": "card-nigeria",
    "amount": 50000,
    "card": {
      "pan": "5061 4604 1012 1111 102",
      "expiry": {
        "month": "12",
        "year": "2050"
      },
      "cvv": "558",
      "cardHolderName": "Emily Heidenreich-Kohler"
    }
  }'

​
Submit PIN

Use this endpoint when the previous response returns data.action as pin. 
curl --request POST \
  --url https://sandbox-api.payfonte.com/payments/v1/cards/pin \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>' \
  --header 'content-type: application/json' \
  --data '{
    "reference": "DCD20260701144120NCDZW",
    "provider": "card-nigeria",
    "card": {
      "pan": "5061 4604 1012 1111 106",
      "expiry": {
        "month": "12",
        "year": "2050"
      },
      "cvv": "562",
      "pin": "1106",
      "cardHolderName": "Donna Flatley"
    }
  }'

​
Submit OTP

Use this endpoint when the previous response returns data.action as otp. 
curl --request POST \
  --url https://sandbox-api.payfonte.com/payments/v1/cards/otp \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>' \
  --header 'content-type: application/json' \
  --data '{
    "reference": "DCD20260701144120NCDZW",
    "otp": "543210"
  }'

​
Response Actions

pin

Collect the customer’s card PIN and call POST /payments/v1/cards/pin with the returned reference.
{
  "statusCode": 200,
  "data": {
    "reference": "DCD20260701133425EIQWF",
    "action": "pin",
    "data": {}
  }
}
Collect the OTP sent to the customer and call POST /payments/v1/cards/otp with the returned reference.
{
  "statusCode": 201,
  "data": {
    "reference": "DCD20260701133425EIQWF",
    "action": "otp",
    "data": {}
  }
}
Redirect the customer to data.data.redirectURL to complete 3DS authentication. After the redirect flow, verify the payment server-side.
{
  "statusCode": 201,
  "data": {
    "reference": "DCD20260701144120NCDZW",
    "action": "redirect",
    "data": {
      "redirectURL": "https://s.6bd.co/card-3ds/mce1aN"
    }
  }
}
Call GET /payments/v1/payments/verify/{reference} with the returned reference to confirm the final transaction status.
{
  "statusCode": 200,
  "data": {
    "reference": "DCD20260701133425EIQWF",
    "action": "verification",
    "data": {}
  }
}

​
Flow Decision Summary

ActionCustomer next stepMerchant next step
pinEnter card PINCall POST /payments/v1/cards/pin
otpShare OTPCall POST /payments/v1/cards/otp
redirectComplete 3DS authenticationRedirect to data.data.redirectURL, then verify
verificationNo further customer inputCall GET /payments/v1/payments/verify/{reference}

​
Important Rules

Amount values must be integers in minor units. Decimals are not supported.
See Amount Specification.
Collect and submit card data only from secure, PCI-compliant environments. Do not log PAN, CVV, PIN, or OTP values.

API Reference

View card payment endpoint definitions and request schemas.

Webhooks

Confirm final transaction outcomes asynchronously.

Testing

Use sandbox card data for PIN, OTP, 3DS, success, failed, and pending scenarios.