Custodians (companies and developers) integrate with the Apto API
to
create and manage branded debit or prepaid cards and cardholder data. We've
tried to make this documentation user-friendly and example-filled, but
please drop us a line with any questions.
When a cardholder uses his or her Apto Card to purchase goods or services, Apto must quickly confirm that the cardholder has sufficient funds prior to authorizing the transaction. A cardholder's spendable balance can be exposed from a custodian's API -or- mainly reside within Apto.
Custodian API provides spendable balance acting as the infallible balance authority. In this case, Apto will request the user's current spendable balance from the custodian's API (your software). Apto will perform basic performance testing of your API prior to launch. Please reach out to Apto Support to discuss integration specifics.
-OR-
Apto stores a spendable balance for each cardholder at card level. Your service simply updates each card balance as it changes within your business logic by consuming Apto's Card Balances.
The Apto API
is architected
around REST, using standard HTTP verbs to communicate and HTTP response
codes to indicate status and errors. All responses come in standard JSON.
The Apto API
is served over HTTPS to ensure data privacy; HTTP is
not supported. Every request must include your secret API key. Request
data must be included in the body.
Apto has a fully supported, production replica sandbox environment https://api.sbx.aptopayments.com. Please reach out for API access.
Apto uses conventional HTTP status codes to communicate success or failure of a request. HTTP codes in the 200-299 indicate successful requests. HTTP codes in the 400-499 range generally are caused by an unsupported or invalid request. HTTP 500 errors are usually caused by an issue or misconfiguration on our backend. Please reach out and we will resolve the issue.
All POST and PUT requests support idempotency as a parameter within the request. Idempotency enables safely retrying requests without duplicating functionality. Idempotency keys need to be uniquely generated by the client for every individual request. We recommend saving off used idempotency keys or using an algorithm with enough entropy to ensure no collisions. Idempotency is useful in operations like ordering a new card, to ensure only one card is ordered when transmission errors occur. Idempotent requests are the equivalent to Apto saving off the original response, including 500 errors caused by Apto, and 400 invalid requests.
Some resources can be paginated. Apto uses a simple cursor based pagination that orders objects based on time of occurance.
The cursor is identified by one of 2 parameters, starting_after
or ending_before
. Both of these parameters take an existing object ID value.
If starting_after is provided, Apto returns the next objects that occurred after the starting_after ID.
Providing the ending_before parameter returns the parameters that occurred just before.
A limit
parameter can also be provided, if not provided the default value will be set to 25. The maximum number of returned elements is limited to 50 independently of the value set in this parameter.
When Apto needs to make backwards incompatible changes to our api, Apto versions all current clients to the current version. These previous versions will be supported, so no changes will be made under your feet. We will let you know that you can upgrade to the latest version for that resource, and you will be able to activate the new version via header when you are ready.
The Apto API uses API keys to authenticate requests. API keys will be provided to you through PGP under request. Authentication occurs through HTTP basic auth. Basic auth is a simple and secure authentication method, and requires a username and password to authenticate all your requests. Your API keys are powerful! Keep them safe and secure. Be careful to not share them within tools such as github or other third parties. Be careful to not embed them within client-side code. API keys should be stored server-side only.
Use the /cardholders
endpoint to create and manage Apto
cardholders. Cardholder objects allow you to track application status and
confirm basic customer info. You can retrieve individual cardholders as
well as a list of all your cardholders.
Know Your Customer:
Each cardholder object includes a kyc_status
. This represents the current state of a user's 'Know Your Customer' identity verification process. More context around a cardholder's kyc_status
is provided with specific (and separate) reason groups.
KYC key | Potential Values |
---|---|
kyc_status | RESUBMIT_DETAILS , UPLOAD_FILE , UNDER_REVIEW , PASSED , REJECTED , TEMPORARY_ERROR , NOT_CHECKED |
kyc_identity_reason | null , WATCHLIST_MATCH , SSN_MISMATCH , SSN_INVALID |
kyc_address_reason | null , ADDRESS_COMMERCIAL , ADDRESS_PO_BOX , ADDRESS_RISKY |
kyc_file_reason | null , UNRELATED_FILE , WRONG_FILE , BLURRY |
KYC reasons will all have a null
value when kyc_status
is PASSED
Create a cardholder. Cardholder objects help to track application status and confirm basic customer info. When a cardholder has passed KYC, they will be ordered a card. POSTing to this same url allows you to update cardholder information.
first_name required | string |
last_name required | string |
custodian_uid | string Your unique user id. |
email required | string |
phone_number required | string E.123 international notation formatted. |
date_of_birth required | string (DateObject) YYYY-MM-DD |
required | object (AddressObject) Apto only supports one address for billing and shipping. We cannot send to P.O boxes. Address can be a point of verification in kyc. |
required | object |
metadata | string You can use this parameter to store a string up to 256 characters with the user. |
object Optional fields to help support multiple types of cards |
{- "first_name": "Josh",
- "last_name": "Wilson",
- "custodian_uid": "your-external-user-id",
- "email": "pat@wilson.com",
- "phone_number": "+16508881111",
- "date_of_birth": "1982-06-20",
- "address": {
- "street_one": "1800 Gates Ave",
- "street_two": "2L",
- "locality": "Ridgewood",
- "region": "NY",
- "postal_code": "11385",
- "country": "USA"
}, - "document": {
- "type": "ssn",
- "value": "490940000"
}, - "metadata": "string",
- "card": {
- "design_key": "blue",
- "program_id": "Apto_GPR",
- "initial_load": {
- "currency": "USD",
- "amount": 200
}, - "metadata": "string",
- "additional_fields": {
- "field_1": "some image url here",
- "field_3": "some qr code here",
- "field_4": "string",
- "field_5": "string"
}
}
}
{- "cardholder": {
- "livemode": false,
- "id": "crdhldr_1cd68f70917cb5ed",
- "corporation_id": "corp_1cd68f70917cb5ed",
- "email": "pat@wilson.com",
- "kyc_passed_at": "2016-10-19T23:20:21.034Z",
- "kyc_status": "PASSED",
- "kyc_identity_reason": null,
- "kyc_address_reason": null,
- "kyc_file_reason": null,
- "first_name": "Josh",
- "last_name": "Wilson",
- "phone": 6157915911,
- "custodian_uid": "your-external-user-id",
- "cards": [
- {
- "card": {
- "id": "crd_fde2d61d233455b9",
- "program_id": "Apto_GPR",
- "design_key": "blue",
- "devices": [
- {
- "name": "Wilson*s iPhone",
- "type": "iPhone",
- "status": "ACTIVE"
}
], - "last_four": "5542",
- "status": "CREATED",
- "dda_number": "9990000267938",
- "aba_routing_number": "121182810",
- "activated_at": "2016-10-19T23:20:21.034Z",
- "network": "VISA",
- "issued_at": "2016-10-19T23:20:21.034Z",
- "shipped_at": "2016-10-19T23:20:21.034Z",
- "created_at": "2016-10-19T23:20:19.000Z",
- "cardholder_id": "crdhldr_1cd68f70917cb5ed",
- "corporation_id": "corp_1cd68f70917cb5ed",
- "ordered_status": "AVAILABLE",
- "number": 4013111122223333,
- "expiration": "03/26",
- "cvv": 123,
- "livemode": true,
- "additional_fields": {
- "field_1": "some image id here",
- "field_3": "some qr code here",
- "field_4": "string",
- "field_5": "string"
}, - "metadata": "string"
}
}
], - "created_at": "2016-10-19T23:20:17.000Z",
- "metadata": "string"
}
}
Returns a paginated array of all cardholders.
starting_after | string Return the page starting right after the specified element. |
ending_before | string Return the page ending right before the specified element. |
limit | string A limit on the number of objects to be returned. Default value is 25. Max allowed value is 50. |
{- "cardholders": [
- {
- "cardholder": {
- "livemode": false,
- "id": "crdhldr_1cd68f70917cb5ed",
- "corporation_id": "corp_1cd68f70917cb5ed",
- "email": "pat@wilson.com",
- "kyc_passed_at": "2016-10-19T23:20:21.034Z",
- "kyc_status": "PASSED",
- "kyc_identity_reason": null,
- "kyc_address_reason": null,
- "kyc_file_reason": null,
- "first_name": "Josh",
- "last_name": "Wilson",
- "phone": 6157915911,
- "custodian_uid": "your-external-user-id",
- "cards": [
- {
- "card": {
- "id": "crd_fde2d61d233455b9",
- "program_id": "Apto_GPR",
- "design_key": "blue",
- "devices": [
- {
- "name": "Wilson*s iPhone",
- "type": "iPhone",
- "status": "ACTIVE"
}
], - "last_four": "5542",
- "status": "CREATED",
- "dda_number": "9990000267938",
- "aba_routing_number": "121182810",
- "activated_at": "2016-10-19T23:20:21.034Z",
- "network": "VISA",
- "issued_at": "2016-10-19T23:20:21.034Z",
- "shipped_at": "2016-10-19T23:20:21.034Z",
- "created_at": "2016-10-19T23:20:19.000Z",