Skip to main content
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 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.

Headers

X-Timestamp
string
required

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.

X-Signature
string
required

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.

User-Agent
string
required

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.

Body

application/json
TransactionId
string
required

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
string
required

An Id representing the External Account Object for the Partner.

PersonalData
object
required

Personal Data of the beneficiary the card is being issued for.

Address
object
required

Address of the beneficiary.

PersonalDocuments
object[]
required

List of identity documents for the Person. May be an empty array when no identity document is on file.

Response

200 - application/json

Ok

CardToken
string
required

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
string
required

Last 4 digits of the card.

ExpirationMonth
integer
required

Expiration month of the card (1-12).

ExpirationYear
integer
required

Expiration year of the card (4 digits).

Success
boolean
required

True if the card was issued successfully / False if the issuance failed.

Address
object

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.

ResponseDescription
string

If the issuance is not successful, the reason should be indicated in this field.