# Card push transfers integration

_To use Card Push Transfers, reach out to [support@increase.com](mailto:support@increase.com)._

Integrating with the Increase API for Card Push Transfers involves three main
concepts:

- [Card Tokens](/documentation/api/card-tokens), which are card numbers collected from your customers that you aim
  to push funds to
- [Card Validations](/documentation/api/card-validations), which are $0 network messages sent to the issuer to ensure
  that the card number is valid and that the cardholder is who they claim to be
- [Card Push Transfers](/documentation/api/card-push-transfers), which push funds to eligible cards

From a high level, your integration would do the following:

1. Collect a customer’s card number. If you’re Payment Card Industry Data
   Security Standards (PCI-DSS) compliant you can do this directly, otherwise
   you’ll likely make use of a tokenization provider. You then forward the card
   number to us at https://vault.increase.com/card_tokens.
2. Check that the card number belongs to a BIN/card range that supports
   push-to-card by calling the [Card Token
   Capabilities](/documentation/api/card-tokens#retrieve-the-capabilities-of-a-card-token)
   endpoint.
3. If it does, you then proceed by confirming with the issuing bank that the
   card number is valid and that the name and address of the cardholder matches
   what they’ve provided you, using the [Card Validation
   creation](/documentation/api/card-validations#create-a-card-validation)
   endpoint.
4. Once confirmed, you push funds to the card with the [Card Push Transfer
   creation](/documentation/api/card-push-transfers#create-a-card-push-transfer)
   endpoint.

If you later want to push funds to the same card again you only need to
repeat step 4.

## Tokenization providers

Increase is fully PCI-DSS compliant and can receive card numbers either directly from
you or from your tokenization provider. By utilizing a tokenization provider you
collect card numbers from your customers using the tokenization provider’s
frontend components, before relying on their forwarding endpoints to pass
through the raw card details to Increase. This ensures that your systems never
see raw card details.

Examples of tokenization providers are:

- Stripe: https://docs.stripe.com/payments/vault-and-forward
- Basis Theory: https://developers.basistheory.com/docs/guides/share/process-card-payments
- Very Good Security: https://www.verygoodsecurity.com/docs/guides/outbound-connection

Increase supports any tokenization provider that can send a JSON payload
over HTTPS.

## Card Tokens

A [Card Token](/documentation/api/card-tokens) is a representation of a card
number encrypted and stored in Increase’s Payment Card Industry (PCI)
environment. The https://vault.increase.com/card_tokens endpoint is the only
endpoint that accepts raw card numbers; everything else uses a Card Token. As
such, the `/card_tokens` endpoint exists at https://vault.increase.com instead
of the regular https://api.increase.com URL.

To authenticate with the `/card_tokens` endpoint you create a special bearer
credential that can only be used for this purpose in the Increase dashboard:
https://dashboard.increase.com/developers/api_keys (`Create API key` → `Create
Production Card Tokenization Key`).

```curl
$ curl -X POST https://vault.increase.com/card_tokens \
  -H "Authorization: Bearer BEARERCREDENTIAL" \
  -H "Content-Type: application/json" \
  -d ’{
    "primary_account_number": "4444440000001234",
    "expiration_month": 3,
    "expiration_year": 2030,
    "card_verification_value2": "123"
  }’

=> {"card_token":"card_token_ooy8ebisb1p71o6lpbbd"}%
```

If you use a tokenization provider like Basis Theory you’ll want to use their
proxy endpoint to forward the request to us:

```curl
$ curl 'https://api.basistheory.com/proxy' \
  -X 'POST' \
  -H 'BT-API-KEY: <API_KEY>' \
  -H 'BT-PROXY-URL: https://vault.increase.com/card_tokens' \
  -H 'Authorization: Bearer BEARERCREDENTIAL' \
  -H 'Content-Type: application/json' \
  -d '{
      "primary_account_number": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
      "expiration_month": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_month\" }}",
      "expiration_year": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_year\" }}",
      "card_verification_value2": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.cvc\" }}",
    }'
```

### Capabilities

Once you’ve tokenized a card number you can fetch its capabilities with the
[Card Token
capabilities](/documentation/api/card-tokens#retrieve-the-capabilities-of-a-card-token)
endpoint. The capabilities are based on routing files provided by the card
networks and return a point-in-time view of the card number at the time of
fetching. Note that retrieving the capabilities of a Card Token only lets you
know that the card number belongs to a valid Account Range on the issuer’s side
and whether it supports actions such as push-to-card transfers; it does not tell
you whether the card number itself is valid. The capabilities can change over
time.

### Sandbox

Real card numbers are not usable in sandbox. Instead you can create
sandbox-specific card tokens using the [Create a Card Token simulation](/documentation/api/card-tokens#sandbox-create-a-card-token).

## Card Validations

[Card Validations](/documentation/api/card-validations) are $0 account
verifications sent to the card network that are used to verify the validity of a
given card number. They also let you validate the cardholder’s information, such
as their name and their address. Since push-to-card transfers are non-reversible
it is crucial to validate that you are pushing funds to the expected cardholder
to prevent fraud.

Similar to other Increase APIs, the [Card Validation
creation](/documentation/api/card-validations#create-a-card-validation) endpoint
creates a `Card Validation` that then moves through an asynchronous state
machine. To retrieve the outcome of a Card Validation you can either use the
[Card Validation
retrieval](/documentation/api/card-validations#retrieve-a-card-validation)
endpoint or listen for
[`card_validation.created`](/documentation/api/events#event-object.category.card_validation.created)
webhooks.

![Card Validations](/images/card-validations-flow.png)

## Card Push Transfers

The [Card Push Transfer
creation](/documentation/api/card-push-transfers#create-a-card-push-transfer)
endpoint initiates a push-to-card transfer. Similar to other Increase transfers
these are asynchronous and move through a state machine in real-time once
created. Card Push Transfers can be declined by the issuer.

The Card Push Transfer input fields depend on your use case. An employee
reimbursement transfer would for example use `business_application_identifier:
funds_disbursement`. To discuss your use case, please reach out to [support@increase.com](mailto:support@increase.com).

Initiating a Card Push Transfer creates a `PendingTransaction` on your Increase
account with a hold for the funds. The `PendingTransaction` is completed as soon
as the Card Push Transfer is either accepted or declined by the issuing bank.
Accepted Card Push Transfers result in a `Transaction`.

![Card Push Transfers](/images/card-push-transfers-flow.png)