Bind a physical card (three card details; no step-up authentication)
x-on-behalf-of required
Requires x-idempotency-key
Assigns a physical card that has reached the user but does not yet belong to anyone to this member. The input consists of three printed card details: card number / expiry date / CVV.
Omitting step-up authentication is deliberate: the CVV is printed only on the back, so these details themselves prove possession. Another verification would merely prevent the card's recipient from binding it. Activation is the truly irreversible step, and additional verification belongs there.
⚠ None of these three details is stored in our database or logs. CVV is compared only in request memory and immediately discarded. We store a keyed HMAC of the card number, not the number itself. Your servers should not retain them either; forwarding them alone already brings you within PCI scope.
⚠ Upstream reassignment is a one-time operation: assigning the card to the wrong person invalidates it with no second chance, and there is no upstream unbind API. A database constraint therefore allows only one reassignment in progress or successful reassignment per card. Do not implement retries as a separate check-then-submit sequence.
⚠ This interface could be used to brute-force card numbers, so it is rate-limited per member to 5 genuine failures in one hour. Network errors and rate-limit rejections themselves do not count. Once reached, the window must expire.
status is always binding: upstream reassignment is asynchronous, and callbacks establish the final state. After the card row exists we also send card.bound: data.id is crd_ and the status is unactivated. This is not activation success.
Prerequisites
- The card exists in inventory and has been dispatched (
shipped). - The member has a physical card application with status
shippedorawaiting_bind. - The member has passed L1 KYC, which we use to create the cardholder upstream.
- Fewer than 5 failed attempts in the last hour.
Request Headers
| Field | Type | Required | Description |
|---|---|---|---|
x-on-behalf-of |
string | Required | The member on whose behalf to call. |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
pan |
string | Required | Full card number. Spaces and hyphens are removed; length 12~19 digits, depending on the network. Do not require exactly 16 digits. |
expiry |
string | Required | Expiry date. Accepts MM/YY / MMYY / MM-YY / MMYYYY; unrecognized formats fail validation. |
cvv |
string | Required | Security code on the back of the card, 3~4 digits. Compared in constant time and immediately discarded. |
application_id |
string | Optional | The application's ID for this card, with or without the cap_ prefix. If omitted, we find the member's pending-binding application automatically. |
Response
{
"application_id": "cap_1b7d90c4-5e2a-4f18-83b6-0c7a4d1e9f22",
"masked_pan": "5240********7890",
"status": "binding"
}code. Wrong card details are not a service failure. Do not retry them as api_error.
invalid_fields (400): the card number length, expiry format, or security-code length is wrong, or the printed details do not match this card.
This response has no fields array, so expiry and the security code cannot be told apart. Show the end user only “the card details are incorrect”.
These attempts count toward the limit of 5 failures per hour.
state_invalid (400): there is no application ready to bind (it must be shipped or awaiting_bind),
a bind is already in progress, or the cardholder is still under review.
kyc_required (400): the member has not passed L1.
product_not_available (400): this BIN or product cannot be bound, or the card is currently unavailable.
cardholder_card_limit (400): this cardholder has reached the card limit. Submitting the same profile again will not succeed.
request_rejected (400): the bind was rejected. Do not keep submitting the same card details.
card_already_used (400): this card has already been used and cannot be linked again. This applies whether it belongs to the current member or another member; the original cardholder is never disclosed. Show “This card has already been used and cannot be linked again” instead of asking the user to retry later.
not_found (404): application_id is not an application for this member.
resource_not_found (404): no inventory card matches this card number, or the inventory is in another state that cannot be linked.
rate_limited (429): 5 real failures have already occurred within the hour. Wait for the window to pass; more submissions do not unlock it early.
upstream_error (502): the upstream is temporarily unavailable. Retry with the same idempotency key. This attempt does not count toward the 5 failures.
invalid_request: the body is not valid JSON.
idempotency_key_required / idempotency_key_invalid.idempotency_key_reused · idempotency_in_progressEmitted Events
Green = successful terminal state · Red = terminal state requiring action · Purple = intermediate state. Open an event for its payload and signature verification details.
curl -X POST 'https://api.zinfra.vip/v1/cards/bind' \
-H 'x-auth-token: Bearer $TOKEN' \
-H 'x-on-behalf-of: $MEMBER_ID' \
-H 'x-idempotency-key: $IDEMPOTENCY_KEY' \
-H 'content-type: application/json' \
-d '{
"pan": "5240121234567890",
"expiry": "08/29",
"cvv": "123"
}'const res = await fetch("https://api.zinfra.vip/v1/cards/bind", {
method: "POST",
headers: {
"x-auth-token": "Bearer $TOKEN",
"x-on-behalf-of": "$MEMBER_ID",
"x-idempotency-key": "$IDEMPOTENCY_KEY",
"content-type": "application/json",
},
body: JSON.stringify({
"pan": "5240121234567890",
"expiry": "08/29",
"cvv": "123"
}),
});
// Keep monetary amounts as strings, never numbers.
const data = await res.json();import requests
res = requests.post(
"https://api.zinfra.vip/v1/cards/bind",
headers={
"x-auth-token": "Bearer $TOKEN",
"x-on-behalf-of": "$MEMBER_ID",
"x-idempotency-key": "$IDEMPOTENCY_KEY",
"content-type": "application/json",
},
json={
"pan": "5240121234567890",
"expiry": "08/29",
"cvv": "123"
},
)
# Use Decimal(str(...)) for amounts, not float.
data = res.json()req, _ := http.NewRequest("POST", "https://api.zinfra.vip/v1/cards/bind",
strings.NewReader(`{
"pan": "5240121234567890",
"expiry": "08/29",
"cvv": "123"
}`))
req.Header.Set("x-auth-token", "Bearer $TOKEN")
req.Header.Set("x-on-behalf-of", "$MEMBER_ID")
req.Header.Set("x-idempotency-key", "$IDEMPOTENCY_KEY")
req.Header.Set("content-type", "application/json")
res, err := http.DefaultClient.Do(req)
// Decode amount fields as string, not float64.HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create("https://api.zinfra.vip/v1/cards/bind"))
.header("x-auth-token", "Bearer $TOKEN")
.header("x-on-behalf-of", "$MEMBER_ID")
.header("x-idempotency-key", "$IDEMPOTENCY_KEY")
.header("content-type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("""
{
"pan": "5240121234567890",
"expiry": "08/29",
"cvv": "123"
}
"""))
.build();
// Use String / BigDecimal for amounts, not double.$ch = curl_init('https://api.zinfra.vip/v1/cards/bind');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'x-auth-token: Bearer $TOKEN',
'x-on-behalf-of: $MEMBER_ID',
'x-idempotency-key: $IDEMPOTENCY_KEY',
'content-type: application/json',
],
CURLOPT_POSTFIELDS => <<<'JSON'
{
"pan": "5240121234567890",
"expiry": "08/29",
"cvv": "123"
}
JSON,
]);
$res = curl_exec($ch);
// Use bcmath / strings for amounts, not floatval.
{
"application_id": "cap_1b7d90c4-5e2a-4f18-83b6-0c7a4d1e9f22",
"masked_pan": "5240********7890",
"status": "binding"
}