> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synctera.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/v2/reference/listexternalcards) 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](/v2/docs/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.

<Info>
  The token will expire after 5 minutes, so ensure External Card creation is performed shortly after card tokenization.
</Info>

Example request:

<CodeGroup>
  ```bash Bash theme={"system"}
  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}"
    }'
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "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"
    }
  }
  ```
</CodeGroup>

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:

| 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.

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](/v2/reference/getexternalcardtransfer) at a later time. Once a transaction is in a *terminal* status, it will not change.

<Warning>
  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](/v2/reference/createexternalcardtransfer) request to force an error to occur.
</Warning>

Example request:

<CodeGroup>
  ```bash Bash theme={"system"}
  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": "janetaylorspub@email.com"
      }
    }'
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "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": "janetaylorspub@email.com"
    },
    "status": "SUCCEEDED",
    "transaction_id": "{TRANSACTION_ID}",
    "type": "PULL"
  }
  ```
</CodeGroup>

`transaction_id` can be used to look up the transaction using the [Transactions API](/v2/reference/gettransactionsbatchpayments).

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:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "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"
  }
  ```
</CodeGroup>

### 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:

<CodeGroup>
  ```bash Bash theme={"system"}
  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,
    }'
  ```
</CodeGroup>

## 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:

<CodeGroup>
  ```shell Shell theme={"system"}
  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
    }'
  ```
</CodeGroup>

Example response:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "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": "janetaylorspub@email.com"
    },
    "status": "SUCCEEDED",
    "transaction_id": "{TRANSACTION_ID}",
    "type": "PULL_REVERSAL"
  }
  ```
</CodeGroup>