External Cards
An External Card on the Synctera platform represents a tokenized debit or credit card with which you may perform transactions. This may be a card external to Synctera or a Synctera issued card. There are three types of transactions which may be performed:
PUSH
: Load funds from a Synctera account onto an External Card.PULL
: Take funds from an External Card to fund a Synctera Account.PULL_REVERSAL
: Reverse aPULL
transaction to load funds back onto an External Card.
This guide will explain how to add an External Card and perform transactions with it.
See External Cards API for more details.
Onboarding
In order to be enabled for External Cards, please reach out your Synctera implementation and onboarding contact.
Add External Card
The first step to adding an External Card is to tokenize the card. To do so, see Link External Cards guide for how to obtain a token
and cardholder name
through the iFrame.
Once the card has been tokenized, use the token
and cardholder name
to create an External Card. person_id
must also be provided and business_id
may optionally be provided if applicable. Note that if business_id
is provided, address verification is performed on the Business's legal address, otherwise, it is performed on the Person's legal address. However, cardholder name
matching is performed on the Person's name regardless.
The token will expire after 5 minutes, so ensure External Card creation is performed shortly after card tokenization.
Example request:
curl \
$baseurl/v0/external_cards/tokens \
-H "Authorization: Bearer $apikey" \
-H 'Content-Type: application/json' \
-d '
{
"token": "{TOKEN}"
"name": "Jane Taylor",
"customer_id": "{CUSTOMER_ID}"
}'
Example response:
{
"created_time": "2023-01-18T12:03:46.892809-05:00",
"currency": "USD",
"customer_id": "{CUSTOMER_ID}",
"expiration_month": "4",
"expiration_year": "2026",
"id": "{EXTERNAL_CARD_ID}",
"last_four": "0004",
"last_modified_time": "2023-01-18T12:03:46.892809-05:00",
"name": "Jane Taylor",
"verifications": {
"address_verification_result": "VERIFIED",
"cvv2_result": "VERIFIED",
"pull_enabled": true,
"push_enabled": true,
"state": "SUCCEEDED"
}
}
The verifications
object contains information about the card, including address verifiation and CVV2 code results, as well as the type of transactions the card supports. If either pull_enabled
or push_enabled
are false
, that type of transaction may not be performed using the card.
Test PANs
The following card PANs can be used in sandbox environment for testing various scenarios:
Network | PAN | Push Enabled | Pull Enabled | Type |
---|---|---|---|---|
Visa | 4005519200000004 | Y | Y | Debit |
Visa | 4217651111111119 | Y | N | Debit |
Visa | 4111111111111111 | Y | Y | Credit |
Mastercard | 2223000048400011 | N | Y | Debit |
Mastercard | 5105105105105100 | N | N | PrePaid |
Create External Card Transaction
Now that an External Card has been tokenized and created, it may be used to perform transactions. An account_id
must be provided, which refers to the Synctera Account that the funds will flow into or out from, depending on the type of transaction.
The merchant
object contains merchant descriptor information that will be shown on financial statements and transaction details. If not provided, default information, defined during onboarding, is used.
Example request:
curl \
$baseurl/v0/external_cards/transfers \
-H "Authorization: Bearer $apikey" \
-H 'Content-Type: application/json' \
-d '
{
"external_card_id": "{EXTERNAL_CARD_ID}",
"originating_account_id": "{ACCOUNT_ID}",
"currency": "USD",
"type": "PULL",
"amount": 2500,
"merchant": {
"name": "Jane Taylor’s Pub",
"address": {
"address_line_1": "4455 Vine Street",
"city": "Lake Forest",
"state": "IL",
"postal_code": "60045",
"country_code": "US"
},
"email": "[email protected]"
}
}'
Example response:
{
"account_id": "{ACCOUNT_ID}",
"amount": 2500,
"country_code": "US",
"created_time": "2023-01-18T17:37:59.449877-05:00",
"currency": "USD",
"customer_id": "{CUSTOMER_ID}",
"id": "{EXTERNAL_CARD_TRANSFER_ID}",
"last_modified_time": "2023-01-18T17:37:59.449877-05:00",
"merchant": {
"name": "Jane Taylor’s Pub",
"address": {
"address_line_1": "4455 Vine Street",
"city": "Lake Forest",
"state": "IL",
"postal_code": "60045",
"country_code": "US"
},
"email": "[email protected]"
},
"status": "SUCCEEDED",
"transaction_id": "{TRANSACTION_ID}",
"type": "PULL"
}
transaction_id
can be used to look up the transaction using the Transactions API.
Reverse External Card Transaction
Reversals can only be applied to PULL
transactions. The full or partial amount may be reversed. However, only one partial reversal may be applied to a single transaction.
Example request:
curl \
$baseurl/v0/external_cards/transfers/{TRANSFER_ID}/reversals \
-H "Authorization: Bearer $apikey" \
-H 'Content-Type: application/json' \
-d '
{
"currency": "USD",
"amount": 2500
}'
Example response:
{
"account_id": "{ACCOUNT_ID}",
"amount": 2500,
"country_code": "US",
"created_time": "2023-01-18T17:53:12.52114-05:00",
"currency": "USD",
"customer_id": "{CUSTOMER_ID}",
"id": "{EXTERNAL_CARD_TRANSFER_REVERSAL_ID}",
"last_modified_time": "2023-01-18T17:53:12.52114-05:00",
"merchant": {
"name": "Jane Taylor’s Pub",
"address": {
"address_line_1": "4455 Vine Street",
"city": "Lake Forest",
"state": "IL",
"postal_code": "60045",
"country_code": "US"
},
"email": "[email protected]"
},
"status": "SUCCEEDED",
"transaction_id": "{TRANSACTION_ID}",
"type": "PULL_REVERSAL"
}
Updated 2 months ago