logo
Documentation Powered by ReDoc

Apto Core API (1.0.0)

E-mail: hello@aptopayments.com Terms of Service

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.

Integration Options

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.

Lay of the land

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.

Sandbox

Apto has a fully supported, production replica sandbox environment https://api.sbx.aptopayments.com. Please reach out for API access.

Errors

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.

Idempotency

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.

Pagination

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, pagination limits can depend on the resource requested. All results are returned in reverse chronological order.

Versioning

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.

Authentication

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.

BasicAuth

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Cardholders

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 Cardholder

post/cardholders

Production

https://api.aptopayments.com/cardholders

Sandbox

https://api.sbx.aptopayments.com/cardholders

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.

Authorizations:
BasicAuth
Request Body schema: application/json
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

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

document
required
object
card
object

Optional fields to help support multiple types of cards

Responses

200
400

invalid_request_error

401

invalid_request_error

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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"
    },
  • "card":
    {
    • "design_key": "blue",
    • "program_id": "Apto_GPR",
    • "initial_load":
      {
      • "currency": "USD",
      • "amount": 200
      },
    • "additional_fields":
      {}
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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":
      [
      • {
        }
      ],
    • "created_at": "2016-10-19T23:20:17.000Z"
    }
}

List Cardholders

get/cardholders

Production

https://api.aptopayments.com/cardholders

Sandbox

https://api.sbx.aptopayments.com/cardholders

Returns a paginated array of all cardholders.

Authorizations:
BasicAuth
query Parameters
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.

Responses

200
400

invalid_request_error

401

invalid_request_error

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "cardholders":
    [
    • {
      • "cardholder":
        {
        }
      }
    ],
  • "has_more": true,
  • "total": 23456
}

Get Cardholder

get/cardholders/{cardholder_id}

Production

https://api.aptopayments.com/cardholders/{cardholder_id}

Sandbox

https://api.sbx.aptopayments.com/cardholders/{cardholder_id}

Cardholder record.

Authorizations:
BasicAuth
path Parameters
cardholder_id
required
string

The identifier of the customer to be retrieved.

Responses

200
400

invalid_request_error

401

invalid_request_error

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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":
      [
      • {
        }
      ],
    • "created_at": "2016-10-19T23:20:17.000Z"
    }
}

Create Cardholder Card

post/cardholders/{cardholder_id}/cards

Production

https://api.aptopayments.com/cardholders/{cardholder_id}/cards