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 a PULL 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"
}