> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leapfinancial.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Beneficiary Card
**This API MUST be implemented by the Partner.** The Platform's backend calls it to issue a card for a beneficiary, backed by the virtual network account.
Our backend will consume this service by performing a `POST` request to:
`[Base-URL]/GetBeneficiaryCard`.
**The path must be respected exactly as specified.** The Partner defines only the `[Base-URL]`; the resource segment `/GetBeneficiaryCard`, the `POST` method and the JSON body are fixed by this contract and are case-sensitive.
**Every request travels signed.** It carries the `X-Timestamp` and `X-Signature` headers with the HMAC-SHA256 signature of the raw body. The Partner must [validate the signature](/vna/client-interfaces/data-integrity) before processing the request.
**Expected behavior:**
Request to issue a physical or virtual card for a beneficiary of the account, using the personal data, address and identity document the Platform has on file for them. The Partner issues the card against its own card processor and returns a tokenized reference to it, along with its last 4 digits and expiration.
**`CardToken` MUST be an alias from the Platform's own VGS vault, never the card number in the clear.** It also MUST keep the last 4 digits at the end of the alias (e.g. `tok_..._1234`). A token that is not an alias of the Platform's vault reaches CrossRiver literally and is rejected — this is not a formatting preference, it is a hard requirement of the integration.
`Last4Digits`, `ExpirationMonth` and `ExpirationYear` travel in their own fields; the Platform does not parse `CardToken` to obtain them.
**`TransactionId` doubles as the idempotency key for the issuance.** It is derived from the beneficiary's external payment method and the number of cards already issued for it. A retry of the same issuance (e.g. after a timeout) arrives with the same `TransactionId`, and the Partner MUST return the same card rather than issuing a new one. A renewal — a new card requested after the previous one expired — arrives with a new `TransactionId` and is expected to result in a new card.
**The `Address` in the response is optional, and if returned it MUST carry at least `CountryCode` and `StateCode`.** The Platform already sends the beneficiary's address in the request and uses it as the card's billing address; only return `Address` if the card was actually issued with a different one. A returned `Address` missing `CountryCode` or `StateCode` is discarded in full, and the Platform keeps the address it sent — it is never merged field by field.
If issuance fails, return `Success` as `false`; the card is not saved on the Platform's side, and `ResponseDescription` is used to record the reason.
## OpenAPI
````yaml vna/swagger-client-interfaces.json POST /client-interfaces/vna/get-beneficiary-card
openapi: 3.0.0
info:
title: ''
version: '3.6'
servers: []
security: []
paths:
/client-interfaces/vna/get-beneficiary-card:
post:
tags:
- Partner Implemented APIs
summary: Get beneficiary card
operationId: getBeneficiaryCardClientApi
parameters:
- in: header
name: X-Timestamp
required: true
description: >-
UTC timestamp in ISO-8601 format with milliseconds
(`yyyy-MM-ddTHH:mm:ss.fffZ`), generated at send time. Its exact
string value is part of the signed message, so it cannot be altered,
and it lets the Partner reject stale requests (replay protection).
See Data Integrity.
schema:
type: string
example: '2026-01-15T18:42:07.123Z'
- in: header
name: X-Signature
required: true
description: >-
HMAC-SHA256 signature of the request, Base64-encoded (standard
alphabet). It is computed over `bytes(X-Timestamp) + bytes(".") +
rawBodyBytes` using the shared secret agreed for the integration.
The Partner MUST validate it — with a constant-time comparison and
over the raw body, before any deserialization — and reject the
request if it does not match. See Data Integrity.
schema:
type: string
example: nQdLCID8zS6tVNG6+Exu5nPiYA8IEAakeo8qVbocKOk=
- in: header
name: User-Agent
required: true
description: >-
Fixed value `VNA`. Sent on every request. Some Partners' WAFs reject
requests without a User-Agent, so the Platform always sets it
explicitly; if the Partner filters by this header, this is the value
to allow.
schema:
type: string
example: VNA
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetBeneficiaryCardRequest'
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/GetBeneficiaryCardResponse'
security: []
components:
schemas:
GetBeneficiaryCardRequest:
properties:
TransactionId:
type: string
description: >-
Unique identifier of the request, used as an idempotency key. It is
derived from the beneficiary's external payment method and the
number of cards already issued for it, so a retry of the same
issuance arrives with the same value — the Partner MUST return the
same card on repeats — while a renewal (a new card requested after
the previous one expired) arrives with a new value.
AccountIdentifier:
type: string
description: An Id representing the External Account Object for the Partner.
PersonalData:
$ref: '#/components/schemas/BeneficiaryCardPersonalData'
description: Personal Data of the beneficiary the card is being issued for.
Address:
$ref: '#/components/schemas/Address'
description: Address of the beneficiary.
PersonalDocuments:
items:
$ref: '#/components/schemas/PersonalDocument'
type: array
description: >-
List of identity documents for the Person. May be an empty array
when no identity document is on file.
required:
- TransactionId
- AccountIdentifier
- PersonalData
- Address
- PersonalDocuments
type: object
additionalProperties: false
GetBeneficiaryCardResponse:
properties:
CardToken:
type: string
description: >-
The issued card, tokenized against the Platform's own VGS vault —
never the card number in the clear. It MUST be an alias from that
vault, and it MUST keep the last 4 digits at the end (e.g.
`tok_..._1234`).
Last4Digits:
type: string
description: Last 4 digits of the card.
ExpirationMonth:
type: integer
description: Expiration month of the card (1-12).
ExpirationYear:
type: integer
description: Expiration year of the card (4 digits).
Address:
$ref: '#/components/schemas/Address'
description: >-
Billing address of the card. Optional: only return it if the address
the card was actually issued with differs from the one sent in the
request. If returned, it MUST carry at least `CountryCode` and
`StateCode` — otherwise it is discarded and the Platform keeps the
`Address` it sent in the request.
Success:
type: boolean
description: >-
True if the card was issued successfully / False if the issuance
failed.
ResponseDescription:
type: string
description: >-
If the issuance is not successful, the reason should be indicated in
this field.
required:
- CardToken
- Last4Digits
- ExpirationMonth
- ExpirationYear
- Success
type: object
additionalProperties: false
BeneficiaryCardPersonalData:
description: >-
Personal information of the beneficiary the card is being issued for. At
least one of `PhoneNumber` or `Email` must be provided.
properties:
PhoneNumber:
type: string
description: |-
User phone number, in E.164 format (e.g. +51987654321).
Required when `Email` is not provided.
Email:
type: string
description: User email address. Required when `PhoneNumber` is not provided.
FirstName:
type: string
description: First Name.
MiddleName:
type: string
description: Middle Name.
LastName:
type: string
description: Last name.
LastName2:
type: string
description: Second last name.
Gender:
type: string
description: 'Gender. Possible values: Male | Female | Other | None.'
BirthDate:
type: string
description: The Birth Date. The accepted format is YYYY-MM-DD.
required:
- FirstName
- LastName
- Gender
type: object
additionalProperties: false
Address:
properties:
Address1:
type: string
description: Address 1.
Address2:
type: string
description: Address 2.
ZipCode:
type: string
description: Zip code.
City:
type: string
description: City.
CountryCode:
type: string
description: >-
A String with the 2-char ISO code (ISO 3166-1 alpha-2) of the
Country.
StateCode:
type: string
description: A String with a 2-character value based on ISO 3166-2.
required:
- CountryCode
- StateCode
type: object
additionalProperties: false
PersonalDocument:
properties:
Number:
type: string
description: The document number.
DocumentType:
$ref: '#/components/schemas/DocumentType'
description: |-
The type of document.
- `Passport` — passport
- `StateId` — state-issued identity card
- `ResidentCard` — permanent resident card
- `DriverLicense` — driver's license
- `SocialSecurityNumber` — social security number
- `INE_IFE` — Mexican INE/IFE voter card
- `ConsularId` — consular identification card
- `ITIN` — individual taxpayer identification number
- `None` — not specified
required:
- Number
- DocumentType
type: object
additionalProperties: false
DocumentType:
type: string
enum:
- None
- Passport
- StateId
- ResidentCard
- DriverLicense
- SocialSecurityNumber
- INE_IFE
- ConsularId
- ITIN
description: |-
Type of identity document.
- `Passport` — passport
- `StateId` — state-issued identity card
- `ResidentCard` — permanent resident card
- `DriverLicense` — driver's license
- `SocialSecurityNumber` — social security number
- `INE_IFE` — Mexican INE/IFE voter card
- `ConsularId` — consular identification card
- `ITIN` — individual taxpayer identification number
- `None` — not specified
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.