Get Beneficiary Card
curl --request POST \
--url https://api.example.com/client-interfaces/vna/get-beneficiary-card \
--header 'Content-Type: application/json' \
--header 'User-Agent: <user-agent>' \
--header 'X-Signature: <x-signature>' \
--header 'X-Timestamp: <x-timestamp>' \
--data '
{
"TransactionId": "<string>",
"AccountIdentifier": "<string>",
"PersonalData": {
"FirstName": "<string>",
"LastName": "<string>",
"Gender": "<string>",
"PhoneNumber": "<string>",
"Email": "<string>",
"MiddleName": "<string>",
"LastName2": "<string>",
"BirthDate": "<string>"
},
"Address": {
"CountryCode": "<string>",
"StateCode": "<string>",
"Address1": "<string>",
"Address2": "<string>",
"ZipCode": "<string>",
"City": "<string>"
},
"PersonalDocuments": [
{
"Number": "<string>"
}
]
}
'import requests
url = "https://api.example.com/client-interfaces/vna/get-beneficiary-card"
payload = {
"TransactionId": "<string>",
"AccountIdentifier": "<string>",
"PersonalData": {
"FirstName": "<string>",
"LastName": "<string>",
"Gender": "<string>",
"PhoneNumber": "<string>",
"Email": "<string>",
"MiddleName": "<string>",
"LastName2": "<string>",
"BirthDate": "<string>"
},
"Address": {
"CountryCode": "<string>",
"StateCode": "<string>",
"Address1": "<string>",
"Address2": "<string>",
"ZipCode": "<string>",
"City": "<string>"
},
"PersonalDocuments": [{ "Number": "<string>" }]
}
headers = {
"X-Timestamp": "<x-timestamp>",
"X-Signature": "<x-signature>",
"User-Agent": "<user-agent>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Timestamp': '<x-timestamp>',
'X-Signature': '<x-signature>',
'User-Agent': '<user-agent>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
TransactionId: '<string>',
AccountIdentifier: '<string>',
PersonalData: {
FirstName: '<string>',
LastName: '<string>',
Gender: '<string>',
PhoneNumber: '<string>',
Email: '<string>',
MiddleName: '<string>',
LastName2: '<string>',
BirthDate: '<string>'
},
Address: {
CountryCode: '<string>',
StateCode: '<string>',
Address1: '<string>',
Address2: '<string>',
ZipCode: '<string>',
City: '<string>'
},
PersonalDocuments: [{Number: '<string>'}]
})
};
fetch('https://api.example.com/client-interfaces/vna/get-beneficiary-card', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/client-interfaces/vna/get-beneficiary-card",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'TransactionId' => '<string>',
'AccountIdentifier' => '<string>',
'PersonalData' => [
'FirstName' => '<string>',
'LastName' => '<string>',
'Gender' => '<string>',
'PhoneNumber' => '<string>',
'Email' => '<string>',
'MiddleName' => '<string>',
'LastName2' => '<string>',
'BirthDate' => '<string>'
],
'Address' => [
'CountryCode' => '<string>',
'StateCode' => '<string>',
'Address1' => '<string>',
'Address2' => '<string>',
'ZipCode' => '<string>',
'City' => '<string>'
],
'PersonalDocuments' => [
[
'Number' => '<string>'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"User-Agent: <user-agent>",
"X-Signature: <x-signature>",
"X-Timestamp: <x-timestamp>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/client-interfaces/vna/get-beneficiary-card"
payload := strings.NewReader("{\n \"TransactionId\": \"<string>\",\n \"AccountIdentifier\": \"<string>\",\n \"PersonalData\": {\n \"FirstName\": \"<string>\",\n \"LastName\": \"<string>\",\n \"Gender\": \"<string>\",\n \"PhoneNumber\": \"<string>\",\n \"Email\": \"<string>\",\n \"MiddleName\": \"<string>\",\n \"LastName2\": \"<string>\",\n \"BirthDate\": \"<string>\"\n },\n \"Address\": {\n \"CountryCode\": \"<string>\",\n \"StateCode\": \"<string>\",\n \"Address1\": \"<string>\",\n \"Address2\": \"<string>\",\n \"ZipCode\": \"<string>\",\n \"City\": \"<string>\"\n },\n \"PersonalDocuments\": [\n {\n \"Number\": \"<string>\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Timestamp", "<x-timestamp>")
req.Header.Add("X-Signature", "<x-signature>")
req.Header.Add("User-Agent", "<user-agent>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/client-interfaces/vna/get-beneficiary-card")
.header("X-Timestamp", "<x-timestamp>")
.header("X-Signature", "<x-signature>")
.header("User-Agent", "<user-agent>")
.header("Content-Type", "application/json")
.body("{\n \"TransactionId\": \"<string>\",\n \"AccountIdentifier\": \"<string>\",\n \"PersonalData\": {\n \"FirstName\": \"<string>\",\n \"LastName\": \"<string>\",\n \"Gender\": \"<string>\",\n \"PhoneNumber\": \"<string>\",\n \"Email\": \"<string>\",\n \"MiddleName\": \"<string>\",\n \"LastName2\": \"<string>\",\n \"BirthDate\": \"<string>\"\n },\n \"Address\": {\n \"CountryCode\": \"<string>\",\n \"StateCode\": \"<string>\",\n \"Address1\": \"<string>\",\n \"Address2\": \"<string>\",\n \"ZipCode\": \"<string>\",\n \"City\": \"<string>\"\n },\n \"PersonalDocuments\": [\n {\n \"Number\": \"<string>\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/client-interfaces/vna/get-beneficiary-card")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Timestamp"] = '<x-timestamp>'
request["X-Signature"] = '<x-signature>'
request["User-Agent"] = '<user-agent>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"TransactionId\": \"<string>\",\n \"AccountIdentifier\": \"<string>\",\n \"PersonalData\": {\n \"FirstName\": \"<string>\",\n \"LastName\": \"<string>\",\n \"Gender\": \"<string>\",\n \"PhoneNumber\": \"<string>\",\n \"Email\": \"<string>\",\n \"MiddleName\": \"<string>\",\n \"LastName2\": \"<string>\",\n \"BirthDate\": \"<string>\"\n },\n \"Address\": {\n \"CountryCode\": \"<string>\",\n \"StateCode\": \"<string>\",\n \"Address1\": \"<string>\",\n \"Address2\": \"<string>\",\n \"ZipCode\": \"<string>\",\n \"City\": \"<string>\"\n },\n \"PersonalDocuments\": [\n {\n \"Number\": \"<string>\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"CardToken": "<string>",
"Last4Digits": "<string>",
"ExpirationMonth": 123,
"ExpirationYear": 123,
"Success": true,
"Address": {
"CountryCode": "<string>",
"StateCode": "<string>",
"Address1": "<string>",
"Address2": "<string>",
"ZipCode": "<string>",
"City": "<string>"
},
"ResponseDescription": "<string>"
}POST request to:
[Base-URL]/GetBeneficiaryCard.
[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.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.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.Success as false; the card is not saved on the Platform’s side, and ResponseDescription is used to record the reason.Headers
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.
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.
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
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.
An Id representing the External Account Object for the Partner.
Personal Data of the beneficiary the card is being issued for.
Show child attributes
Show child attributes
Address of the beneficiary.
Show child attributes
Show child attributes
List of identity documents for the Person. May be an empty array when no identity document is on file.
Show child attributes
Show child attributes
Response
Ok
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).
Last 4 digits of the card.
Expiration month of the card (1-12).
Expiration year of the card (4 digits).
True if the card was issued successfully / False if the issuance failed.
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.
Show child attributes
Show child attributes
If the issuance is not successful, the reason should be indicated in this field.