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:

1. PUSH: Load funds from a Synctera account onto an External Card.
2. PULL: Take funds from an External Card to fund a Synctera Account.
3. 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.

Testing

The following card PANs can be used in sandbox environment for testing various scenarios:

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.

The status field of the response indicates the outcome of the transaction:

• SUCCEEDED: The transaction was successful and funds are available - terminal status
• DECLINED: The transaction could not be completed due to a specific rule, e.g. low balance or velocity control - terminal status
• CANCELED: The transaction could not be completed due to error, e.g. upstream processing error - terminal status
• UNKNOWN: The transaction status is indeterminate - non-terminal status
• PENDING: The transaction has been initialized - non-terminal status

For the non-terminal status, you can subscribe to the EXTERNAL_CARD_TRANSFER.UPDATED webhook to be notified of status change, or simply Get External Card Transfer at a later time. Once a transaction is in a terminal status, it will not change.

⚠️

Be aware that while testing in the sandbox environment, amount values 1, 1100, 2, 1200, 3, 1300, 4 and 1400 are special values reserved for generating upstream processor errors. They can be used in any Create External Card Transfer request to force an error to occur.

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}",
  "external_card_id": "{EXTERNAL_CARD_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.

If you receive the following response, it means 3-D Secure is required for this transaction and three_ds_id must be provided. See External Cards 3-D Secure (3DS) guide for more information. Note that this is only applicable to PULL transactions.

Response:

{
  "code": "EXTERNAL_CARD_TRANSFER_3DS_REQUIRED",
  "detail": "3-D Secure authorization required for this external card transfer",
  "status": 422,
  "title": "Rule Violation",
  "type": "https://dev.synctera.com/errors/rule-violation"
}

Me-to-You PUSH Transactions

In the typical case, the originating Account and the External Card are assumed to be owned by the same Person (me-to-me transaction). However, it's also possible to initiate a (PUSH only) transaction to an External Card owned by Person who is not the originating Account owner (me-to-you transaction). In this scenario, originating_customer_id is supplied with the Person who owns the originating Account.

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_customer_id": "{CUSTOMER_ID}": 
    "originating_account_id": "{ACCOUNT_ID}",
    "currency": "USD",
    "type": "PULL",
    "amount": 1000,
  }'

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/{EXTERNAL_CARD_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}",
  "external_card_id": "{EXTERNAL_CARD_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"
}