Issuing cards

This article explains how to issue cards using the Apto Core API and the Apto Mobile API. You can also issue cards using the mobile SDK. For details, see the Apto mobile SDK docs on issuing cards for iOS or Android.

Issuing cards with the Core API#

note

Issuing cards with the Core API is only possible in the sandbox and in Enterprise programs. In Instant Issuance programs, cards in production are issued through the Mobile API.

Card issuance using the Core API is a single-step process that creates a cardholder object, conducts KYC (Know Your Customer) on the data provided, and issues a card for the cardholder. It is a single request that returns the cardholder data and the cardholder’s KYC status. This is in contrast to the Mobile API, which requires that you first authenticate the applicant using 2FA to secure a session token before proceeding.

To issue a card in the Core API, submit a POST request to the /cardholders endpoint with cardholder data. For example:

{
"first_name": "Josh",
"last_name": "Wilson",
"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"
}
}

The response to this request includes the cardholder state, cardholder data, card type, and card state.

{
"cardholder": {
"livemode": false,
"id": "crdhldr_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",
"ordered_status": "AVAILABLE",
"number": 4013111122223333,
"expiration": "03/26",
"cvv": 123,
"livemode": true,
"additional_fields": {
"field_1": "some image id here",
"field_2": "https://dummyimage.com/600x400/000/fff.png",
"field_3": "some qr code here",
"field_4": "string",
"field_5": "string"
}
}
}
],
"created_at": "2016-10-19T23:20:17.000Z"
}
}

The cardholder state refers to the cardholder’s KYC status and whether it is “passed”, “not passed”, or “pending”. The card type refers to whether the issued card is digital or physical.

Card state refers to the card’s lifecycle, shown here:

StateDescription
CreatedCards that have been created, but not yet activated. This state only applies to physical cards.
ActivatedCards that are activated can be used to conduct transactions.
DeactivatedCardholders can freeze their cards temporarily. In this state, incoming transactions for this card are rejected by our transaction authorization module. Cardholders can activate deactivated cards at any time.
ClosedCards can be closed by our customer support team for a variety of reasons: lost or stolen cards, cards expired, etc. Incoming transactions for closed cards are rejected by our transaction authorization module. Closed cards cannot be reopened.

Issuing cards with the Mobile API#

note

Issuing cards with the Mobile API is for Enterprise integrations. However, our SDKs wrap the Mobile API. For more, see the Apto Mobile SDK docs for iOS or Android.

Card issuance with the Mobile API is a multi-step process:

  1. Verify the applicant and generate a secure session token
  2. Create a cardholder object
  3. Issue a card

Step 1: Verify a cardholder’s primary credential#

You can begin the verification process by sending a POST request to the /verifications/start endpoint with the applicant’s phone number:

{
"datapoint_type": "phone",
"datapoint": {
"country_code": "1",
"phone_number": "2025550141"
}
}

When you submit this request, we send a one-time password (OTP) via SMS to the applicant’s phone number. The OTP expires after 15 minutes. The response includes a verification object, identified by the verification_id field—with a status of “pending”:

{
"type": "verification",
"verification_id": "entity_27288bc122db1339",
"status": "pending"
}

The applicant must enter the OTP in the app. Then the app can send a POST request with this password to the /verifications/{verification_id}/finish endpoint to complete the verification.

{
"secret": "string"
}

The response includes the status of the verification, which can be "pending", "passed", "failed", or "expired":

{
"type": "verification",
"verification_id": "entity_27288bc122db1339",
"status": "passed"
}

Once the applicant’s verification is “passed”, you can use their primary credential to create a cardholder object.

Step 2: Create a cardholder object#

To create a cardholder object from a verified primary credential, send a POST request to the /user endpoint:

{
"data_points": {
"type": "list",
"data": [
{
"type": "phone",
"country_code": "1",
"phone_number": "2025550141"
}
]
}
}

This request makes sure the primary credential verification is valid, and then creates the cardholder object. The response contains the user_id and user_token for the new cardholder:

{
"type": "user",
"user_id": "crdhldr_b04f29605a018f7d72a2",
"user_token": "E5PWX4T9dcPriIo ... ao0QZLC6YL/dAyaA8",
"user_data": {
"type": "list",
"data": [
{
"type": "phone",
"country_code": "1",
"phone_number": "2025550141"
}
],
"page": 0,
"rows": 5,
"has_more": true,
"total_rows": 10
}
}

Step 3: Issue a card#

To issue a card, send a POST request to the /user/accounts/issuecard endpoint with the applicant’s user token:

{
"type": "card",
"balance_version": "v1",
"card_product_id": "entity_entity_ed56f762f2c407fa",
"balance_store": {
"type": "custodian",
"custodian_type": "coinbase",
"credential": {
"type": "credential",
"credential_type": "oauth",
"access_token": "3a1psty6xga9qhbbjp7j95sisw69pqfl02zxmwlfg2ryqnoz23ucygxfusfw7qvb",
"refresh_token": "nllp1sr5p2jzqhx4geosztae63rk3hqe5dfbe254dil0wr5boe7bpinuhjqku17f"
}
}
}

The response contains the basic, non-PCI-protected data of the card, including the card’s state, which can be "active", "inactive", "cancelled", "created", or "unknown".

{
"type": "card",
"account_id": "crd_98hnhu9sc7i9ay73375",
"last_four": "1234",
"card_network": "VISA",
"card_brand": "Marvel Card",
"card_issuer": "Apto Payments",
"expiration": "2021-03",
"pan": "4000123456739010",
"cvv": "123",
"state": "active",
"kyc_status": "resubmit_details",
"kyc_reason": "Please contact customer service to check your ID documents",
"spendable_today": {
"currency": "USD",
"amount": "1457.87"
},
"native_spendable_today": {
"currency": "USD",
"amount": "1457.87"
},
"total_balance": {
"currency": "USD",
"amount": "1457.87"
},
"native_total_balance": {
"currency": "USD",
"amount": "1457.87"
},
"ordered_status": "ordered",
"cardholder_first_name": "Anthony",
"cardholder_last_name": "Stark",
"issued_at": "2019-07-30T07:03:55+00:00",
"name_on_card": "TONY STARK",
"features": {
"get_pin": {
"status": "enabled",
"type": "IVR",
"ivr_phone": {
"country_code": 1,
"phone_number": 9366666715
}
},
"set_pin": {
"status": "enabled",
"type": "IVR",
"ivr_phone": {
"country_code": 1,
"phone_number": 9366666715
}
},
"support": {
"status": "enabled",
"type": "IVR",
"ivr_phone": {
"country_code": 1,
"phone_number": 9366666715
}
},
"card_style": {
"background": {
"background_type": "COLOR",
"background_color": "string",
"background_image": "string",
"card_logo": "string"
},
"text_color": "string"
},
"add_funds": {
"status": "enabled",
"soft_descriptor": "My company descriptor",
"card_networks": ["MASTERCARD"],
"limits": {
"daily": {
"max": {
"currency": "USD",
"amount": "1457.87"
},
"remaining": {
"currency": "USD",
"amount": "1457.87"
}
},
"monthly": {
"max": {
"currency": "USD",
"amount": "1457.87"
},
"remaining": {
"currency": "USD",
"amount": "1457.87"
}
}
}
}
}
}