Cards
Binding a customer card with an SMS code
A customer is identified by externalUserId, the user ID in your system. There is no separate call to create
a customer: it appears with the first card binding.
Binding
Authorization
bearer In: header
Header Parameters
8 to 128 characters [A-Za-z0-9._:-], unique per operation
^[A-Za-z0-9._:-]{8,128}$Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/cards" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "externalUserId": "user-42", "cardNumber": "8600123456789012", "expiryMonth": 9, "expiryYear": 29, "phone": "998901234567" }'{ "success": true, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "processingTimeMs": 0 }, "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "externalUserId": "string", "status": "PENDING_CONFIRMATION", "mask": "string", "expiry": "string", "otpSentPhone": "string", "createdAt": "2019-08-24T14:15:22Z" }}Authorization
bearer In: header
Path Parameters
uuidRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/cards/497f6eca-6276-4993-bfeb-53cbbbba6f08/confirm" \ -H "Content-Type: application/json" \ -d '{ "otp": "111111" }'{ "success": true, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "processingTimeMs": 0 }, "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "externalUserId": "string", "status": "PENDING_CONFIRMATION", "mask": "string", "expiry": "string", "otpSentPhone": "string", "createdAt": "2019-08-24T14:15:22Z" }}POST /v1/cardswith the card number and expiry β statusPENDING_CONFIRMATION, the cardholder receives an SMS.POST /v1/cards/{id}/confirmwith the code β statusACTIVE.
If the same card is already bound to this customer and active, step 1 returns it right away without an SMS. Binding an unconfirmed card again replaces the previous attempt: that is how "resend the code" works.
What we store
Only the provider token, a mask like 860012******9012, the expiry date and a fingerprint used to find duplicates.
The full card number is never stored anywhere.
Access across merchants
By default a customer's cards are shared by all merchants of your business. In the merchant settings you can switch to "this merchant only". Cards of different businesses are never visible to each other.
Listing and removal
Authorization
bearer In: header
Path Parameters
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/customers/string/cards"{ "success": true, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "processingTimeMs": 0 }, "data": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "externalUserId": "string", "status": "PENDING_CONFIRMATION", "mask": "string", "expiry": "string", "otpSentPhone": "string", "createdAt": "2019-08-24T14:15:22Z" } ]}Authorization
bearer In: header
Path Parameters
uuidResponse Body
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/v1/cards/497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "success": true, "meta": { "requestId": "string", "timestamp": "2019-08-24T14:15:22Z", "processingTimeMs": 0 }, "data": { "removed": true }}GET /v1/customers/{externalUserId}/cardsreturns the active cards available to the merchant.DELETE /v1/cards/{id}removes a card.