Register a new credit card

This Tango API endpoint allows you to add a credit card to a Tango account so it can be used for funding activities. A credit card must be registered before initiating a funding transaction. A registered credit cards can be used to fund your account immediately. Learn more about Register a new credit card with Tango API.

Once a card is successfully registered, the API returns an activation date. Funding with the newly registered card must occur after this activation date. Any funding attempt before the activation date will result in an error. All funding calls must include the origin token returned during credit‑card registration.

📘

Notes:

• Only credit card funding is currently accessible through Tango API.
• Each Tango platform can store up to 10 registered cards and is encouraged to audit them every 60–90 days for cleanup. Delete any credit card that you do not wish to use, or has been expired.
• Credit card transactions are subject to a 2.9% processing fee.

Use case

Acme Health runs wellness programs that reward members for completing healthy‑behavior tasks such as annual checkups and preventative screenings. Acme Health uses Tango to automate reward delivery at scale. To streamline funding, Acme Health pre‑funds its Tango accounts using a corporate credit card. Because Tango requires that a credit card be registered before it can be used for funding, the finance team provides the required parameters—including the customer identifier, account identifier, IP address, etc. in a POST request to the POST {URI}/creditCards endpoint to complete the registration process. When Acme registers a credit card using the Tango API, the system creates a unique origin token tied to that specific credit card. This token is essential because it becomes the required credential for all future funding attempts using that card.

Endpoint

Use the following endpoint to register a new credit card on your platform:

Parameters

When registering a new credit card with the Tango API, the request body includes a set of required and optional fields. These fields ensure proper identification of the customer, card details, billing information, and optional notification contacts:

How to register a new credit card?

This is how the registration process works:

1. You submit the registration request including the body parameters above.
2. Tango returns a registration response with a token in the response body. The token is the key identifier for the credit card in all future operations. The token is not the card number and cannot be regenerated by the client — it is created only once during registration.
3. You must wait until the activation date. The card becomes usable for funding only after the activation date included in the response.
4. The token must be used for all funding operations. Tango uses the token to identify the stored credit card, charge the correct card, and apply the deposit to the appropriate account. Without it the funding call fails.
5. You can retrieve the card (and token) later. Registered cards along with their stored contact information can be fetched via GET {URI}/creditCards. This returns the previously issued token so you can continue funding operations without re‑registering the card.

Register a new credit card in the sandbox environment

When testing credit card registration in the Tango Sandbox environment, you must use the supported test card numbers provided below. Each number represents a specific card brand (e.g., Visa, MasterCard) and must be paired with the correct type of security code. Only these test numbers are supported in the Sandbox; real or alternative card numbers will not work.

See the test credit card numbers below:

Test credit card registered with sandbox

After registering a test credit card in the Tango API Sandbox, we recommend verifying that it behaves as expected. The Sandbox simulates credit‑card deposit outcomes based on the test amount you submit. Each test amount triggers a predictable sequence of status updates—typically beginning with PENDING and transitioning within about one hour.

The table below outlines the expected pending status, simulated transitions, and final outcomes:

The following example shows the payload registering a Visa card with sandbox:

{
  "accountIdentifier": "string", (5-100 chars)
  "billingAddress": {
    "addressLine1": "123 Street",
    "addressLine2": "Suite 456",
    "city": "Seattle",
    "country": "US",
    "emailAddress": "[email protected]",
    "firstName": "First",
    "lastName": "Last",
    "postalCode": "12345",
    "state": "WA"
  },
  "creditCard": {
    "expiration": "2025-12",
    "number": "4111111111111111",
    "verificationNumber": "123"
  },
  "customerIdentifier": "string", (5-100 chars)
  "ipAddress": "100.10.SAMPLE.10",
  "label": "Test Card"
}

Get an email receipt when registering your credit card

For credit cards successfully registered on or after March 22, 2018, Tango automatically sends credit card funding receipts to the primary email address provided in the registration request, and up to five additional contacts specified during registration. Each contact is defined by an emailAddress and fullName.

Contacts included in a successful registration request are returned in the API response and you can retrieve them at any time using GET {URI}/creditCards.

Email receipts are issued after a successful funding attempt has completed processing, the credit card has been charged, and the associated account balance is updated.

📘

Note:

For security reasons, the primary email address provided during credit card registration cannot be modified. To change the contacts where receipts are sent, the credit card must be deleted and re-registered with a new contact.

Examples

Here's an example payload for when you receive an error:

{
  "timestamp": "2025-02-21T23:23:13.930Z",
  "requestId": "string",
  "path": "string",
  "httpCode": 0,
  "httpPhrase": "string",
  "i18nKey": "string",
  "message": "The error message will show here for error codes ",
  "errors": [
    {}
  ]
}

Response codes

The possible response codes for this endpoint are as follows. For details, see i18nkey codes and their error messages: