Integration

To use Card Push Transfers, reach out to support@increase.com.

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

• Card Tokens, which are card numbers collected from your customers that you aim to push funds to
• 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, 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 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 endpoint.
4. Once confirmed, you push funds to the card with the Card Push Transfer creation 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 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 an 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 -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 '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 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.

Card Validations

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 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 endpoint or listen for card_validation.created webhooks.

Card Push Transfers

The Card Push Transfer creation 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.

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.