Collections - Card API
Submit card details and continue card collections through PIN, OTP, 3DS redirect, or verification actions.
Card payments may require more than one API call before JGME Pay 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
See Testing for how to validate card flows.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://api.jgmepay.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/jgmepay",
"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://api.jgmepay.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://api.jgmepay.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": {}
}
}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
| 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.