Collections - Card API

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

Method	Endpoint	Purpose
`POST`	`/payments/v1/cards/process`	Submit card details and start the card payment
`POST`	`/payments/v1/cards/pin`	Submit card PIN when the response action is `pin`
`POST`	`/payments/v1/cards/otp`	Submit 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

Submit card details

Call /payments/v1/cards/process with provider, amount, and card. You can also pass root-level reference, redirectURL, and webhook values for transaction tracking, customer return, and webhook override behavior. Send your client identifier in the client-id header.

Read the action

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

Continue the required step

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

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 '{
    "reference": "ORDER-1001",
    "provider": "card-nigeria",
    "amount": 50000,
    "redirectURL": "https://yourapp.com/payment/complete",
    "webhook": "https://yourapp.com/webhooks/payfonte",
    "card": {
      "pan": "5061 4604 1012 1111 102",
      "expiry": {
        "month": "12",
        "year": "2050"
      },
      "cvv": "558",
      "cardHolderName": "Emily Heidenreich-Kohler",
      "email": "Darrick.OHara@hotmail.com",
      "phoneNumber": "(536) 393-0857",
      "address": "Address 1, Lokoja",
      "city": "my-city"
    }
  }'

Request Fields

Field	Type	Required	Description
`provider`	string	Yes	Card provider slug, for example `card-nigeria`
`amount`	integer	Yes	Amount in minor units
`card`	object	Yes	Card and customer billing details
`reference`	string	Recommended	Unique transaction identifier from your system
`redirectURL`	string	No	Customer return URL after payment
`webhook`	string	No	Per-transaction webhook override URL

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",
      "email": "Darrick.OHara@hotmail.com",
      "phoneNumber": "(536) 393-0857",
      "address": "Address 1, Lokoja",
      "city": "my-city"
    }
  }'

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

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": {}
  }
}

otp

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

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"
    }
  }
}

verification

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

Action	Customer next step	Merchant next step
`pin`	Enter card PIN	Call `POST /payments/v1/cards/pin`
`otp`	Share OTP	Call `POST /payments/v1/cards/otp`
`redirect`	Complete 3DS authentication	Redirect to `data.data.redirectURL`, then verify
`verification`	No further customer input	Call `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.

Getting Started

Core Concepts

Providers & Coverage

Development

Collect Payment

Disbursements

Collections - Card API

Endpoints

Testing

Integration Steps

Submit Card Details

Request Fields

Submit PIN

Submit OTP

Response Actions

Flow Decision Summary

Important Rules

API Reference

Webhooks

Testing

​Endpoints

​Testing

​Integration Steps

​Submit Card Details

​Request Fields

​Submit PIN

​Submit OTP

​Response Actions

​Flow Decision Summary

​Important Rules

​Related Docs

API Reference

Webhooks

Testing

Endpoints

Testing

Integration Steps

Submit Card Details

Request Fields

Submit PIN

Submit OTP

Response Actions

Flow Decision Summary

Important Rules

Related Docs