Apto API

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.

Guide

Lay of the land
Cardholders
Cards
Card Batches
Transactions
- Retrieve a transaction
- List all transactions
Webhooks
Remittances

Integration Options

When a cardholder uses his or her Apto Card to purchase goods or services, Apto's software must quickly confirm 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.

API Endpoint

https://api.aptopayments.com

Authentication

Authentication to the API occurs via HTTP Basic Auth. Provide your API publishable key as the basic auth username and the your API secret key as the password.

Live mode and testing

Every account is divided into two universes: one for testing, and one for running on your live website. All API requests exist in one of those two universes, and objects in one universe cannot be manipulated by objects in the other.

Errors

status code 401

{
  "error": {
    "type": "invalid_request_error",
    "message": "Authentication to the API occurs via HTTP Basic Auth"
  }
}

status code 400

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid region provided (must be US two letter state)"
  }
}

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 inlcudes 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`
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

POST /cardholders

In test mode:

New users and cards are created but cards are not physically shipped and will not work over the Visa network.
kyc_status is returned as PASSED when the last 4 digits of the provided SSN are '0000'.

Arguments

Parameter	Type	Details
first_name	required
last_name	required
email	required
phone_number	required	E.164 number formatting
address	required	International address object
date_of_birth	required	ISO8601 Date format
document	required	Identity document object
custodian_uid	optional	Unique identifier of custodian's user
card -> id	optional	In case card already exists
card -> design_key	optional	Apto card design key string
card -> program_id	optional	Apto Card Program id
card -> name_on_card	optional	Apto Name on card
card -> initial_load -> amount	optional	Apto Card initial load amount
card -> initial_load -> currency	optional	Apto Card initial load amount currency
card -> additional_fields	optional	Additional fields to store data
wallets	optional	Wallet ids

Example Request Body

{
	"first_name": "Josh",
	"last_name": "Wilson",
	"custodian_uid": "your-external-user-id",
	"email": "[email protected]",
	"phone_number": "6157915911",
	"date_of_birth": "1982-06-20",
	"design_key": "blue", # deprecated, should be send inside card object
	"address": {
		"street_one": "1800 Gates Ave",
		"street_two": "2L",
		"locality": "Ridgewood",
		"region": "NY",
		"postal_code": "11385",
		"country": "USA"
	},
	"document": {
		"type": "SSN",
		"value": "490940000"
	},
	"card": {
	    	"id": "crd_c7015aecb8a05618",
		"design_key": "blue",
		"program_id": "Apto_GPR",
		"name_on_card: "JOSH WILSON",
		"initial_load": {
			"currency": "USD",
			"amount": 200.00
		},
		"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": ...,
			"field_5": ...
		}
	},
	"wallets": [{
	     "id": '48a59504-eba4-42f1-96f3-358b894245e'
	}]
}

Example Response:

status code 200

{
	"cardholder": {
		"livemode": false,
		"id": "crdhldr_1cd68f70917cb5ed",
		"email": "[email protected]",
		"kyc_passed_at": "2016-10-19T23:20:21.034+00:00",
		"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_c7015aecb8a05618",
				"program_id": "Apto_GPR",
				"design_key": "blue",
				"livemode": false,
				"devices": [],
				"last_four": "5542",
				"status": "CREATED",
				"dda_number": '9990000267938',
				"aba_routing_number": '121182810',
				"activated_at": null,
				"created_at": "2016-10-19T23:20:19+00:00",
				"cardholder_id": "crdhldr_1cd68f70917cb5ed",
				"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": ...,
					"field_5": ...

				}
			}
		}],
		"created_at": "2016-10-19T23:20:17+00:00"
	}
}

Update a cardholder

POST /cardholders

In test mode:

New users and cards are created but cards are not physically shipped and will not work over the Visa network.
kyc_status is returned as PASSED when the last 4 digits of the provided SSN are '0000'.

Arguments

Parameter	Type	Details
first_name	required
last_name	required
email	required
phone_number	optional	E.164 number formatting
address	optional	International address object
date_of_birth	optional	ISO8601 Date format
document	optional	Identity document object
custodian_uid	optional	Unique identifier of custodian's user
card -> additional_fields	optional	Additional fields to store data
wallets	optional	Ids of external funding source wallets/accounts.

Example Request Body

{
	"first_name": "Josh",
	"last_name": "Wilson",
	"custodian_uid": "your-external-user-id",
	"email": "[email protected]",
	"phone_number": "6157915911",
	"date_of_birth": "1982-06-20",
	"design_key": "blue", # deprecated, should be send inside card object
	"address": {
		"street_one": "1800 Gates Ave",
		"street_two": "2L",
		"locality": "Ridgewood",
		"region": "NY",
		"postal_code": "11385",
		"country": "USA"
	},
	"document": {
		"type": "SSN",
		"value": "490940000"
	},
	"card": {
		"additional_fields": {
			"field_1": "updated image id here",
			"field_2": "https://updatedimage.com/600x400/000/fff.png",
			"field_3": "updated qr code here",
			"field_4": ...,
			"field_5": ...
		}
	},
	"wallets": [{
	     "id": '48a59504-eba4-42f1-96f3-358b894245e'
	}]
}

Example Response:

status code 200

{
	"cardholder": {
		"livemode": false,
		"id": "crdhldr_1cd68f70917cb5ed",
		"email": "[email protected]",
		"kyc_passed_at": "2016-10-19T23:20:21.034+00:00",
		"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_c7015aecb8a05618",
				"program_id": "Apto_GPR",
				"design_key": "blue",
				"livemode": false,
				"devices": [],
				"last_four": "5542",
				"status": "CREATED",
				"dda_number": '9990000267938',
				"aba_routing_number": '121182810',
				"activated_at": null,
				"created_at": "2016-10-19T23:20:19+00:00",
				"cardholder_id": "crdhldr_1cd68f70917cb5ed",
				"additional_fields": {
					"field_1": "updated image id here",
					"field_2": "https://updatedimage.com/600x400/000/fff.png",
					"field_3": "updated qr code here"
				}
			}
		}],
		"created_at": "2016-10-19T23:20:17+00:00"
	}
}

Retrieve a cardholder

GET /cardholders/[cardholder_id]

Arguments

Parameter	Type	Details
cardholder	required	The identifier of the customer to be retrieved.

List all cardholders

GET /cardholders

Arguments

Parameter	Type	Details
limit	optional	A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
ending_before	optional	A cursor for use in pagination. An object ID that defines your place in the list.
starting_after	optional	A cursor for use in pagination. An object ID that defines your place in the list.

Example Response:

status code 200

{
	"cardholders": [
		{"cardholder": ... }, 
		{"cardholder": ... }
	}],
	"has_more": true
}

Cardholder Cards

Create a cardholder card

POST /cardholders/[cardholder_id]/cards

Arguments

Parameter	Type	Details
cardholder	required	The identifier of the customer to be retrieved.
design_key	required	Apto card design key string
program_id	required	Apto Card Program id
initial_load -> amount	required	Apto Card initial load amount
initial_load -> currency	required	Apto Card initial load amount currency

Example Request Body

{
 	"design_key": "blue",
	"program_id": "Apto_GPR",
	"initial_load": {
		"currency": "USD",
		"amount": 200.00
	}
}

Example Response:

status code 200

{
    "cardholder": {
        "livemode": true,
        "id": "crdhldr_95a80dad9f712d660c44",
        "email": "[email protected]",
        "kyc_passed_at": "2019-09-05T20:33:02.828+00:00",
        "kyc_status": "PASSED",
        "kyc_identity_reason": null,
        "kyc_address_reason": null,
        "kyc_file_reason": null,
        "kyc_files_required": null,
        "first_name": "Josh",
        "last_name": "Wilson",
        "phone": "+17123456789",
        "custodian_uid": "294dc729-b752-815z-af69-e24f3353dc989",
        "cards": [
            {
                "card": {
                    "id": "crd_02a29ff5f62d518a",
                    "design_key": "blue",
                    "livemode": true,
                    "wallets": [],
                    "program_id": "Apto_US",
                    "event": null,
                    "last_four": "6145",
                    "status": "CREATED",
                    "activated_at": null,
                    "created_at": "2017-09-05T20:33:04+00:00",
                    "issued_at": null,
                    "shipped_at": null,
                    "cardholder_id": "crdhldr_95a80dad9f712d660c44",
                    "network": "VISA",
                    "ledge_account_id": null,
                    "ordered_status": "ORDERED",
                    "allow_set_pin": false,
                    "allow_get_pin": true,
                    "program_profile_id": "Apto_US",
                    "cardholder_first_name": "Josh",
                    "cardholder_last_name": "Wilson",
                    "dda_number": null,
                    "aba_routing_number": null,
                    "wait_list": false,
                    "name_on_card": "JOSH WILSON",
                    "allow_international": false,
                    "spendable_today": {
                        "amount": 0.0,
                        "currency": "USD",
                        "native_amount": 0.0,
                        "native_currency": "USD"
                    },
                    "spendable_balance": {
                        "amount": 0.0,
                        "currency": "USD",
                        "native_amount": 0.0,
                        "native_currency": "USD"
                    },
                    "total_balance": {
                        "amount": 0.0,
                        "currency": "USD",
                        "native_amount": 0.0,
                        "native_currency": "USD"
                    }
                }
            }
        ],
        "address": {
            "street_one": "1800 Gates Ave",
            "street_two": "2L",
            "locality": "Ridgewood",
            "region": "NY",
            "postal_code": "11386",
            "country": "USA"
        },
        "event": null,
        "created_at": "2019-09-05T20:33:02+00:00"
    }
}

Cardholder Transactions

Create a cardholder transaction (testmode only)

POST /cardholders/[cardholder_id]/transactions

Note: This API is applicable in case if custodian authorizes and maintains the balance

Arguments

Parameter	Type	Details
cardholder	required	The identifier of the cardholder.
debit -> amount	required	Debit amount to post transaction
debit -> currency	required	Debit amount currency
Example Request Body:

{
	"debit": {
		"currency": "USD",
		"amount": 200.00
	}
}

Example Response:

status code 200

{
	"transaction": {
		"livemode": false,
		"id": "txn_12aa2c96a548d7d2",
		"authorizations": [],
		"adjustments": [],
		"cardholder_id": "crdhldr_1cd68f70917cb5ed",
		"created_at": "2016-10-19T23:25:17+00:00",
		"cardholder_email": "[email protected]",
		"cardholder_first_name": "Josh",
		"cardholder_last_name": "Wilson",
		"card_id": "crd_c7015aecb8a05618",
		"description": "",
		"merchant_name": null,
		"merchant_locality": null,
		"merchant_region": null,
		"merchant_country": null,
		"mcc": "7299",
		"mcc_name": "Undefined",
		"mcc_group": "Food and Beverage",
		"merchant_id": null,
		"state": "pending",
		"context": "PIN purchase (VISA, Signature)",
		"local_currency": "EUR",
		"local_currency_code": "978",

		"local_amount": {
			"currency": "EUR",
			"amount": 50.00
		},
		"settlement_amount": {
			"currency": "USD",
			"amount": 65.00
		},
		"hold_amount": {
			"currency": "USD",
			"amount": 0.00
		},
		"billing_amount": {  # provided under request
			"currency": "USD",
			"amount": 67.50
		},
		"cashback_amount": {
			"currency": "USD",
			"amount": 0.00
		},
		"fee_amount": {
			"currency": "USD",
			"amount": 2.50
		},
		"native_balance_amount": { # internal api's only
			"currency": "BTC",
			"amount": 0.012
		},
		"card_present": false,
		"ecommerce": false,
		"international": false,
		"emv": false,
		"network": "VISA",
		"dispute_at": null,
		"dispute_won_at": null,
		"dispute_lost_at": null
	}
}

List all cardholder transactions

GET /cardholders/[cardholder_id]/transactions

Arguments

Parameter	Type	Details
cardholder	required	The identifier of the customer to be retrieved.
limit	optional	A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
ending_before	optional	A cursor for use in pagination. An object ID that defines your place in the list.
starting_after	optional	A cursor for use in pagination. An object ID that defines your place in the list.

Example Response:

status code 200

{
	"transactions": [
		{"transaction": ... }, 
		{"transaction": ... }
	}],
	"has_more": true
}

Cardholder Balances

The ability to manage multiple spendable balances (buckets) and perform credits for each cardholder.

Note: Cardholder balances APIs are applicable in case if custodian authorizes and maintains the balance

Retrieve a cardholder balances

GET /cardholders/[cardholder_id]/cards/[card_id]/balances

Arguments

Parameter	Type	Details
cardholder	required	The identifier of the customer to be retrieved.
card	required	The identifier of the customer's card to be retrieved.

Example Response:

status code 200

{
	"balances": [{
	    "balance": {
		"id": "bal_ced86e0gf379f255",
		"version": "v2",
		"type": "default",
		"name": "Default",
		"state": "VALID",
		"currency": "USD",
		"total_amount": 10,
		"spendable_amount": 10,
		"held_amount": 0,
		"native_id": "4054598e-q7ca-36c1-93d0-eafae0935vdl",
		"native_currency": "USD",
		"native_amount": 10
	    }
	}]
}

Retrieve cardholder current balance

GET /cardholders/[cardholder_id]/cards/[card_id]/balance

Arguments

Parameter	Type	Details
cardholder	required	The identifier of the customer to be retrieved.
card	required	The identifier of the customer's card to be retrieved.

Example Response:

status code 200

{
	"balance": {
		"id": "bal_ced86e0gf379f255",
		"version": "v2",
		"type": "default",
		"name": "Default",
		"state": "VALID",
		"currency": "USD",
		"total_amount": 10,
		"spendable_amount": 10,
		"held_amount": 0,
		"native_id": "4054598e-q7ca-36c1-93d0-eafae0935vdl",
		"native_currency": "USD",
		"native_amount": 10
	 }
}

Cards

Use the /cards endpoint to retrieve card info, to update card PIN, to change card status, to view transactions on specific card, to view balance on card and to deibit/credit the card balance.

status for a given card object can be one of four states: CREATED, ACTIVATED, DEACTIVATED, or CLOSED

Retrieve a card

GET /cards/[card_id]

Arguments

Parameter	Type	Details
card	required	The identifier of the cardholder's card.

Example Response:

status code 200

{
	"card": {
		"id": "crd_fde2d61d233455b9",
		"program_id": "Apto_GPR",
		"design_key": "blue",
		"livemode": true,
		"devices": [{
			"device": {
				"name": "Wilson*s iPhone",
				"type": "iPhone",
				"status": "ACTIVE"
			}
		}],
		"last_four": "9497",
		"status": "ACTIVATED",
		"dda_number": '9990000267938',
		"aba_routing_number": '121182810',
		"activated_at": "2016-09-27T01:46:32+00:00",
		"created_at": "2016-09-27T00:54:09+00:00",
		"cardholder_id": "crdhldr_2d0a6443e5da6ba7"
	}
}

Wallet lifecycle

Status	Description
INACTIVE	Provisioned with wallet provider, but not yet active
ACTIVE	Active wallet / card instance
SUSPENDED	Temporarily unusable
DELETED	Permanently unusable

Change card PIN

PUT /cards/[card_id]/pin

Arguments

Parameter	Type	Details
card	required	The identifier of the cardholder's card.
new_pin	required	4-digit card pin.

Change card status

PUT /cards/[card_id]/[action]

Arguments

Parameter	Type	Details
card	required	The identifier of the cardholder's card.
action	required	One of the following strings: "ACTIVATE", "DEACTIVATE", "OPEN", "REISSUE" or "CLOSE".
reissued_card_id	optional	In case of REISSUE event, newly issued (pre-printed) card id can be passed in request.

Example Response:

status code 200

{
	"card": {
		"id": "crd_fde2d61d233455b9",
		"program_id": "Apto_GPR",
		"design_key": "blue",
		"livemode": true,
		"devices": [{
			"device": {
				"name": "Wilson*s iPhone",
				"type": "iPhone",
				"status": "ACTIVE"
			}
		}],
		"last_four": "9497",
		"status": "DEACTIVATED",
		"dda_number": '9990000267938',
		"aba_routing_number": '121182810',
		"activated_at": "2016-09-27T01:46:32+00:00",
		"created_at": "2016-09-27T00:54:09+00:00",
		"cardholder_id": "crdhldr_2d0a6443e5da6ba7"
	}
}

List all card transactions

GET /cards/[card_id]/transactions

Arguments

Parameter	Type	Details
card	required	The identifier of the card to be retrieved.
limit	optional	A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
ending_before	optional	A cursor for use in pagination. An object ID that defines your place in the list.
starting_after	optional	A cursor for use in pagination. An object ID that defines your place in the list.

Example Response:

status code 200

{
	"transactions": [
		{"transaction": ... }, 
		{"transaction": ... }
	}],
	"has_more": true
}

Order Physical Card

POST /cardholders/[cardholder_id]/cards/[card_id_str]/order_physical

Arguments

Parameter	Type	Details
cardholder	required	The identifier of the cardholder to be retrieved.
card	required	The identifier of the card to be retrieved.

Example Response:

status code 200

{
	"card": {
		"id": "crd_fde2d61d233455b9",
		"program_id": "Apto_GPR",
		"design_key": "blue",
		"livemode": true,
		"devices": [{
			"device": {
				"name": "Wilson*s iPhone",
				"type": "iPhone",
				"status": "ACTIVE"
			}
		}],
		"last_four": "9497",
		"status": "CREATED",
		"dda_number": '9990000267938',
		"aba_routing_number": '121182810',
		"activated_at": "2016-09-27T01:46:32+00:00",
		"created_at": "2016-09-27T00:54:09+00:00",
		"cardholder_id": "crdhldr_2d0a6443e5da6ba7",
		"ordered_status": "ORDERED"
		"additional_fields": {
			"field_1": "some image id here",
			"field_2": "https://dummyimage.com/600x400/000/fff.png",
			"field_3": "some qr code here"
		}

	}
}

Activate physical card

POST /cardholders/[cardholder_id]/cards/[card_id_str]/activate_physical

Arguments

Parameter	Type	Details
activation_code	required	6 digit activation code
cardholder	required	The identifier of the cardholder to be retrieved.
card	required	The identifier of the card to be retrieved.

Example Response:

status code 200

{
	"card": {
		"id": "crd_fde2d61d233455b9",
		"program_id": "Apto_GPR",
		"design_key": "blue",
		"livemode": true,
		"devices": [{
			"device": {
				"name": "Wilson*s iPhone",
				"type": "iPhone",
				"status": "ACTIVE"
			}
		}],
		"last_four": "9497",
		"status": "ACTIVATED",
		"dda_number": '9990000267938',
		"aba_routing_number": '121182810',
		"activated_at": "2016-09-27T01:46:32+00:00",
		"created_at": "2016-09-27T00:54:09+00:00",
		"cardholder_id": "crdhldr_2d0a6443e5da6ba7",
		"ordered_status": "RECEIVED"
	}
}

Card Balances

The ability to manage spendable balances for each card.

Note: Card balances APIs are applicable in case if Apto authorizes and maintains the balance

Retrieve a card balance

GET /cards/[card_id]/balances

Arguments

Parameter	Type	Details
card	required	The identifier of the card to be retrieved.

Example Response:

status code 200

{
	"balances": [{
	    "balance": {
		"id": "bal_ced86e0gf379f255",
		"version": "v2",
		"type": "default",
		"name": "Default",
		"state": "VALID",
		"currency": "USD",
		"total_amount": 10,
		"spendable_amount": 10,
		"held_amount": 0,
		"native_id": "4054598e-q7ca-36c1-93d0-eafae0935vdl",
		"native_currency": "USD",
		"native_amount": 10
	    }
	}]
}

Debit balance on card

Debit the balance on card.

POST /cards/[card_id]/balances/debits

Arguments

Parameter	Type	Details
card	required	The identifier of the card to be retrieved.
debit -> amount	required	Amount to debit.
debit -> currency	required	Amount Currency.
idempotency_key	required	Unique Idempotency Key Per Request.
description	required	Description.
forced_post	optional	In case of 'true', It will by pass all the business rules and post the transaction on the card. By default its value will be 'false'.

Example Request Body

{
	"debit": {
		"currency": "USD",
		"amount": 50.00
	},
	"idempotency_key": "abcd1234",
	"description": "Debit $50",
	"forced_post": "true"
}

Example Response:

status code 200

{
	"balances": [{
	    "balance": {
		"id": "bal_ced86e0gf379f255",
		"version": "v2",
		"type": "default",
		"name": "Default",
		"state": "VALID",
		"currency": "USD",
		"total_amount": 10,
		"spendable_amount": 10,
		"held_amount": 0,
		"native_id": "4054598e-q7ca-36c1-93d0-eafae0935vdl",
		"native_currency": "USD",
		"native_amount": 10
	    }
	}]
}

Credit balance on card

Credit the balance on card.

POST /cards/[card_id]/balances/credits

Arguments

Parameter	Type	Details
card	required	The identifier of the card to be retrieved.
credit -> amount	required	Amount to credit.
credit -> currency	required	Amount Currency.
idempotency_key	required	Unique Idempotency Key Per Request.
description	required	Description.
forced_post	optional	In case of 'true', It will by pass all the business rules and post the transaction on the card. By default its value will be 'false'.

Example Request Body

{
	"credit": {
		"currency": "USD",
		"amount": 50.00
	},
	"idempotency_key": "abcd1234",
	"description": "Debit $50",
	"forced_post": "true"
}

Example Response:

status code 200

{
	"balances": [{
	    "balance": {
		"id": "bal_ced86e0gf379f255",
		"version": "v2",
		"type": "default",
		"name": "Default",
		"state": "VALID",
		"currency": "USD",
		"total_amount": 10,
		"spendable_amount": 10,
		"held_amount": 0,
		"native_id": "4054598e-q7ca-36c1-93d0-eafae0935vdl",
		"native_currency": "USD",
		"native_amount": 10
	    }
	}]
}

Card Batches

Use the /card-batches endpoint to create and get the detail of card batches.

Create Bulk Cards

POST /card-batches

It will initiate the bulk card order request.

Arguments

Parameter	Type	Details
cards_quantity	required	Number of cards required to generate
address	optional	International card shipment address object
card_details -> design_key	optional	Apto card design key string
card_details -> program_id	optional	Apto Card Program id
card_details -> initial_load -> amount	optional	Apto Card initial load amount
card_details -> initial_load -> currency	optional	Apto Card initial load amount currency

Example Request Body

{
	"cards_quantity": "10",
	"card_details": {
	    	"design_key": "blue",
		"program_id": "Apto_GPR",
		"initial_load": {
			"currency": "USD",
			"amount": 2000
		}
	},
	"address": {
		"street_one": "1800 Gates Ave",
		"street_two": "2L",
		"locality": "Ridgewood",
		"region": "NY",
		"postal_code": "11385",
		"country": "USA"
	}
}

Example Response:

status code 200

{
	"card_batch":{
		"batch_id": "cbt_fde2d61d233335b3",
		"batch_status": "LOGGED",
		"batch_requested_at": "2018-05-27T00:54:09+00:00
		"cards_quantity": 10,
		"cards_generated": 0
		"card_details": {
	    		"design_key": "blue",
			"program_id": "Apto_GPR",
			"initial_load": {
				"currency": "USD",
				"amount": 2000
			}
		},
		"card_ids":[]
	}
}

Card Batches lifecycle

Status	Description
LOGGED	Cards Batch request successfully logged
INPROGRESS	Card records generation is in-progress
COMPLETED	Card records generation has been completed successfully
CANCELED	Card records generation request has been canceled

Retrieve a Card Batch Details

GET /card-batches/[card_batch_id]

Arguments

Parameter	Type	Details
card_batch_id	required	The identifier of Card Batch to be retrieved.

Example Response:

status code 200

{
	"card_batch":{
		"batch_id": "cbt_fde2d61d233335b3",
		"batch_status": "INPROGRESS",
		"batch_requested_at": "2018-05-27T00:54:09+00:00
		"cards_quantity": 10,
		"cards_generated": 3
		"card_details": {
	    		"design_key": "blue",
			"program_id": "Apto_GPR",
			"initial_load": {
				"currency": "USD",
				"amount": 2000
			}
		},
		"card_ids":[
			"crd_c7015aecb8a03338",
			"crd_c7015aecb8a05618",
			"crd_c7015aecb8a02228"
		]
	}
}

Cancel Card Batch

PUT /card-batches/[card_batch_id]/cancel

Arguments

Parameter	Type	Details
card_batch_id	required	The identifier of Card Batch to be retrieved.

Example Response:

status code 200

{
	"card_batch":{
		"batch_id": "cbt_fde2d61d233335b3",
		"batch_status": "CANCELLED",
		"batch_requested_at": "2018-05-27T00:54:09+00:00
		"cards_quantity": 10,
		"cards_generated": 3
		"card_details": {
	    		"design_key": "blue",
			"program_id": "Apto_GPR",
			"initial_load": {
				"currency": "USD",
				"amount": 2000
			}
		},
		"card_ids":[
			"crd_c7015aecb8a03338",
			"crd_c7015aecb8a05618",
			"crd_c7015aecb8a02228"
		]
	}
}

Transactions

Use the /transactions endpoint to retrieve Apto cardholder currency movement records.

Each transaction object inlcudes state represetning the current state of a transaction's lifecycle. state can be one of three values: pending, complete or declined.

Retrieve a transaction

GET /transactions/[transaction_id]

Arguments

Parameter	Type	Details
transaction	required	The identifier of the transaction to be retrieved.

Example Response:

status code 200

{
	"transaction": {
		"livemode": false,
		"id": "txn_12aa2c96a548d7d2",
		"authorizations": [],
		"adjustments": [
		  {
		    "adjustment": {
		      "id": "adj_3bc9dcf557975fe4",
		      "created_at": "2018-07-04T15:15:51+00:00",
		      "local_amount": {
		        "amount": -23.57,
		        "currency": "USD"
		      },
		      "billing_amount": {
		        "amount": -23.57,
		        "currency": "USD"
		      },
		      "native_amount": {
		        "amount": -0.002511,
		        "currency": "BTC"
		      },
		      "native_fee_amount": {
		        "amount": -0.000060732497853052926,
		        "currency": "BTC"
		      },
		      "funding_source_transaction_id": "5447cbb1-9d8a-4f37-5715-4aef3238641e",
		      "funding_source_name": "",
		      "exchange_rate": 9385.42,
		      "type": "capture"
		    }
		  }
		],
		"balances": [{
		    "balance": {
			"id": "bal_ced86e0gf379f255",
			"version": "v2",
			"type": "default",
			"name": "Default",
			"state": "VALID",
			"currency": "USD",
			"total_amount": 10,
			"spendable_amount": 10,
			"held_amount": 0,
			"native_id": "4054598e-q7ca-36c1-93d0-eafae0935vdl",
			"native_currency": "USD",
			"native_amount": 10
		    }
		}],
		"merchant": {
		  "found": false,
		  "latitude": null,
		  "longitude": null,
		  "name": null,
		  "formatted_address": null,
		  "street_number": null,
		  "street": null,
		  "locality": null,
		  "region": null,
		  "country": null,
		  "postal_code": null,
		  "external_id": null
		},
		"local_amount": {
			"currency": "USD",
			"amount": -23.57
		},
		"hold_amount": {
			"currency": "USD",
			"amount": 0.00
		},
		"billing_amount": {  # provided under request
			"currency": "USD",
			"amount": -23.57
		},
		"cashback_amount": {
			"currency": "USD",
			"amount": 0.00
		},
		"fee_amount": {
			"currency": "USD",
			"amount": 2.50
		},
		"native_balance_amount": { # internal api's only
			"currency": "BTC",
			"amount": 0.012
		},
		"cardholder_id": "crdhldr_1cd68f70917cb5ed",
		"created_at": "2016-10-19T23:25:17+00:00",
		"cardholder_email": "[email protected]",
		"cardholder_first_name": "Josh",
		"cardholder_last_name": "Wilson",
		"card_id": "crd_c7015aecb8a05618",
		"card_present": true,
		"description": "",
		"mcc": "7299",
		"mcc_name": "Undefined",
		"mcc_group": "Food and Beverage",
		"merchant_name": "LORDS PHARMACY LTD",
		"merchant_locality": "LONDON",
		"merchant_region": "",
		"merchant_country": "GBR",
		"state": "pending",
		"context": "PIN purchase (VISA, Signature)",
		"local_currency": "EUR",
		"local_currency_code": "978",
		"type": "PIN_PURCHASE",
		"card_present": false,
		"ecommerce": false,
		"international": false,
		"emv": false,
		"network": "VISA",
		"shift_stand_in": false,
		"dispute_id": null,,
		"dispute_at": null,
		"dispute_won_at": null,
		"dispute_lost_at": null,
		"funding_source_name": "BTC Wallet",
		"decline_reason": "",
		"decline_code": "",
		"idempotency_key": null
	}
}

List all transactions

GET /transactions

Arguments

Parameter	Type	Details
limit	optional	A limit on the number of objects to be returned. Limit can range between 1 and 100 items.
ending_before	optional	A cursor for use in pagination. An object ID that defines your place in the list.
starting_after	optional	A cursor for use in pagination. An object ID that defines your place in the list.

Example Response:

status code 200

{
  "transactions": [
    {...}, 
    {...}
  ],
  "has_more": false
}

Webhooks

The Apto API can push real-time data directly to your application server. Use webhooks to be notified about events that happen with your account and cardholders including transaction authorization, transaction updates and settlement information.

Creating a webhoook endpoint on your server is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Sinatra, you would add a new route with the desired URL.

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. Any other information returned in the request headers or request body is ignored. All response codes outside this range, including 3xx codes, will indicate to Apto that you did not receive the webhook.

If a webhook is not successfully received for any reason, Apto will continue trying to send the webhook once an hour for up to 2 days. For any webhook that failed initially, upon retry each hour, the latest state for the Apto object will be sent.

KYC Status Updates

Response:

Parameter	Details
kyc_status	Possible values can be: PASSED, REJECTED, UPLOAD_FILE, RESUBMIT_DETAILS, UNDER_REVIEW, NOT_APPLICABLE, TEMPORARY_ERROR

Events that can trigger KYC status updates:

user update
kyc status update
idedntity update

status code 200

{
	"cardholder": {
		"livemode": false,
		"id": "crdhldr_1cd68f70917cb5ed",
		"email": "[email protected]",
		"event": "kyc_status_update",
		"kyc_passed_at": "2016-10-19T23:20:21.034+00:00",
		"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_c7015aecb8a05618",
				"program_id": "Apto_GPR",
				"design_key": "blue",
				"livemode": false,
				"devices": [],
				"last_four": "5542",
				"status": "CREATED",
				"activated_at": null,
				"created_at": "2016-10-19T23:20:19+00:00",
				"cardholder_id": "crdhldr_1cd68f70917cb5ed"
			}
		}],
		"created_at": "2016-10-19T23:20:17+00:00"
	}
}

Card Updates

Response:

Parameter	Details
status	Possible values can be: CREATED, ACTIVATED, UPLOAD_FILE, DEACTIVATED, CLOSED

Events that can trigger card updates:

card update
status update
card sent
pin change

{
	"card": {
		"id": "crd_fde2d61d233455b9",
		"program_id": "Apto_GPR",
		"design_key": "blue",
		"livemode": true,
		"event": "pin_update",
		"devices": [{
			"device": {
				"name": "Wilson*s iPhone",
				"type": "iPhone",
				"status": "ACTIVE"
			}
		}],
		"last_four": "9497",
		"status": "ACTIVATED",
		"dda_number": '9990000267938',
		"aba_routing_number": '121182810',
		"activated_at": "2016-09-27T01:46:32+00:00",
		"created_at": "2016-09-27T00:54:09+00:00",
		"cardholder_id": "crdhldr_2d0a6443e5da6ba7"
	}
}

Daily Settlement

{
	"settlement": {
		"livemode": true,
		"id": "stlmnt_5hfi35",
		"date": "2016-05-24T16:36:24+00:00",
		"total_balance_due": 56943.05,
		"period_balance_due": 6281.39,
		"csv_url": "https://example.aptopayments.com/settlements/stlmnt_5hfi35"
	}
}

Transaction Updates

Response:

Parameter	Details
adjustments	Apto creates internal adjustments for each of the transaction.
local_amount	This is the actual transaction amount.
billing_amount	This is the local amount plus fee for the transaction (if any)
idempotency_key	Unique for each transaction

{
	"transaction": {
		"livemode": false,
		"id": "txn_12aa2c96a548d7d2",
		"authorizations": [], // For specific clients only
		"adjustments": [
		  {
		    "adjustment": {
		      "id": "adj_3bc9dcf557975fe4",
		      "created_at": "2018-07-04T15:15:51+00:00",
		      "local_amount": {
		        "amount": -23.57,
		        "currency": "USD"
		      },
		      "billing_amount": {
		        "amount": -23.57,
		        "currency": "USD"
		      },
		      "native_amount": {
		        "amount": -0.002511,
		        "currency": "BTC"
		      },
		      "native_fee_amount": {
		        "amount": -0.000060732497853052926,
		        "currency": "BTC"
		      },
		      "funding_source_transaction_id": "5447cbb1-9d8a-4f37-5715-4aef3238641e",
		      "funding_source_name": "",
		      "exchange_rate": 9385.42,
		      "type": "capture"
		    }
		  }
		],
		"balances": [{
		    "balance": {
			"id": "bal_ced86e0gf379f255",
			"version": "v2",
			"type": "default",
			"name": "Default",
			"state": "VALID",
			"currency": "USD",
			"total_amount": 10,
			"spendable_amount": 10,
			"held_amount": 0,
			"native_id": "4054598e-q7ca-36c1-93d0-eafae0935vdl",
			"native_currency": "USD",
			"native_amount": 10
		    }
		}],
		"merchant": {  //For internal use only
		  "found": false,
		  "latitude": null,
		  "longitude": null,
		  "name": null,
		  "formatted_address": null,
		  "street_number": null,
		  "street": null,
		  "locality": null,
		  "region": null,
		  "country": null,
		  "postal_code": null,
		  "external_id": null
		},
		"local_amount": {
			"currency": "USD",
			"amount": -23.57
		},
		"hold_amount": {
			"currency": "USD",
			"amount": 0.00
		},
		"billing_amount": {  # provided under request
			"currency": "USD",
			"amount": -23.57
		},
		"cashback_amount": {
			"currency": "USD",
			"amount": 0.00
		},
		"fee_amount": {
			"currency": "USD",
			"amount": 2.50
		},
		"native_balance_amount": { # internal api's only
			"currency": "BTC",
			"amount": 0.012
		},
		"cardholder_id": "crdhldr_1cd68f70917cb5ed",
		"created_at": "2016-10-19T23:25:17+00:00",
		"cardholder_email": "[email protected]",
		"cardholder_first_name": "Josh",
		"cardholder_last_name": "Wilson",
		"card_id": "crd_c7015aecb8a05618",
		"card_present": true,
		"description": "",
		"mcc": "7299",
			"mcc_name": "Undefined",
		"mcc_group": "Food and Beverage",
		"merchant_name": "LORDS PHARMACY LTD",
		"merchant_locality": "LONDON",
		"merchant_region": "",
		"merchant_country": "GBR",
		"state": "pending",
		"context": "PIN purchase (VISA, Signature)",
		"local_currency": "EUR",
		"local_currency_code": "978",
		"type": "PIN_PURCHASE",
		"card_present": false,
		"ecommerce": false,
		"international": false,
		"emv": false,
		"network": "VISA",
		"shift_stand_in": false,
		"dispute_id": null,,
		"dispute_at": null,
		"dispute_won_at": null,
		"dispute_lost_at": null,
		"funding_source_name": "BTC Wallet",
		"decline_reason": "",
		"decline_code": "",
		"idempotency_key": null
	}
}

Card Batch Updates

{
	"card_batch":{
		"batch_id": "cbt_fde2d61d233335b3",
		"batch_status": "COMPLETED",
		"batch_requested_at": "2018-05-27T00:54:09+00:00
		"cards_quantity": 10,
		"cards_generated": 10
		"card_details": {
	    		"design_key": "blue",
			"program_id": "Apto_GPR",
			"initial_load": {
				"currency": "USD",
				"amount": 2000
			}
		},
		"card_ids":["crd_c7015aecb8a03338",
			"crd_c7015aecb8a05618","crd_c7015aecb8a02228",
			"crd_c7015aecb8a11218","crd_c4015fecb8a43678",
			"crd_c7015adcb8a23128","crd_c7515eecb8a91838",
			"crd_c7015aacb8a98768","crd_c7615decb8a83748",
			"crd_c7015abcb9109878"
			]
	}
}

Remittances

Apto's Remittance module enables to transfer funds to supported bank accounts and pickup locations.

API Objects

Here we are listing main objects of Apto's Remittance API to know about the information provided in these objects.

Country

"country" :  {
    "country_id": "ARG",
    "country_name": "ARGENTINA",
    "payment_modes":[
        {...},
        {...},
    ],
    "payment_currencies":[
        {...},
        {...},
    ]
}

State

"state" : {
    "state_id": "CA",
    "state_name": "CALIFORNIA",
    "cities":[
        {...},
        {...},
        {...},
    ]
}

City

"city" : {
    "city_id": "MX440",
    "state_id": "MEX22",
    "city_name": "ZOQUIAPAN",
    "state_name": "PUEBLA",
    "payment_modes":[
        {...},
        {...},
    ],
    "payment_currencies":[
        {...},
        {...},
    ]
}

KYC Photo Type

"kyc_photo_type":{
    "photo_id_type": "BF",
    "photo_id_name": "CPF/CNPJ"
}

Assessed Exchange Rate

"assessed_exchange_rate":{
    "exchange_rate": "2700.00"
}

Payment Network

"payment_network":{
    "payment_network_id": "U53003"
    "payment_network_name": "BANCO PROVIDENCIAL",
    "logo_name": "//s3-bucket/path/to/logo/USA40108.svg",
    "number_of_locations": 775,
    "recipient_phone_required": false,
    "routing_required": true
}

Payment Location

"payment_location":{
    "payment_location_id": "BC0001",
    "payment_location_name": "BANCOLOMBIA",
    "payment_network_name": "BANCOLOMBIA",
    "address": "xx, xxxxxx, xxxxxx,xxxx,",
    "business_hours": "L-J 8:00AM-4:30PM;V:8:00AM-5:00PM",
    "recipient_phone_required": false,
    "cash_pickup_available": false,
    "bank_deposit_available": true,
    "home_delivery_available": false,
    "pays_local_currency": true,
    "pays_USD": false,
    "latitude": "0.0000",
    "longitude": "0.0000"
}

Payment Mode

"payment_mode":{
    "payment_mode": "C",
    "payment_mode_name": "BANK (DEPOSIT)"
}

Payment Currency

"payment_currency":{
    "currency_type": "N",
    "currency_id": "MXN",
    "currency_name": "MEXICAN PESO"
}

Cost Model

"cost_model":{
    "exchange_rate":{
        "date_requested": "2017-10-19T23:20:21.034+00:00",
        "exchange_rate": "2700.00",
        "non_kyc_limit": "999.99",
        "maximum_to_send": "3000.00",
        "minimum_to_send": "1.00"
    },
    "transaction_fee":{
        "total_fee": "240.00"
        "fees_types": [
            {
                "fee_type": "customer_fix_fee",
                "amount": "0.00"
            },
            {
                "fee_type": "customer_percentage_fee",
                "amount": "240.00"
            },
            {
                "fee_type": "funding_fee",
                "amount": "0.00"
            },
            {
                "fee_type": "state_tax",
                "amount": "0.00"
            },
        ]
    }
}

Sender

"sender":{
    "sender_id": "1",
    "first_name": "MATTHEW",
    "middle_name": null,
    "last_name": "GALLOWAY",
    "address1": "77 EASTWOOD COURTT, SAN JOSE, CA",
    "address2": null,
    "phone1": "6508617544",
    "phone2": null,
    "city_id": "95101",
    "state_id": "CA   ",
    "zip_code": "95116",
    "country_id": "USA  ",
    "photo_id_country": "USA",
    "photo_id_type": "EA",
    "photo_id": "123",
    "birth_date": "09-09-1988",
    "email": "[email protected]",
    "country_of_birth": null,
    "external_uid": null,
}

Recipient

"recipient":{
    "sender_id": "1",
    "recipient_id": "1",
    "first_name": "MATTHEW",
    "middle_name": null,
    "last_name": "GALLOWAY",
    "address1": "77 EASTWOOD COURTT, SAN JOSE, CA",
    "address2": null,
    "phone1": "6508617544",
    "phone2": null,
    "city_id": "95101",
    "state_id": "CA   ",
    "zip_code": "95116",
    "country_id": "USA  ",
    "birth_date": "09-09-1988",
    "email": "[email protected]",
    "country_of_birth": null,
}

Recipient Bank Account

"recipient_bank_account":{
    "sender_id": "1",
    "recipient_id": "1",
    "bank_account_id": "22669",
    "routing_number": "123456780",
    "bank_account_number": "123456788",
    "nick_name": "Mash",
    "bank_account_type": "S",
    "bank_account_type_name": "Saving",
    "payment_network_id": "A00042",
    "payment_network_name": null
}

Remittance Transaction

"transaction" : {
    "transaction_id": "10",
    "sender_id" : "1",
    "recipient_id" : "1",
    "transaction_date": "2016-10-19T23:20:21.034+00:00",
    "funds_availability_date": "2018-12-06",
    
    "money_transfer_ref_no": "0042712110",
    "payment_mode": "P",
    "currency_type": "N",
    "transaction_status": "H",
    "status_description": "HOLD",
    "require_additional_information": false,

    "payment_location_id": "BC0002",
    "payment_network_name": "BANCOLOMBIA",
    "payment_location_address": "EN EL EDIF COLTEJER LA QUE DA HACIA LA PLAYA CR 49 N 52-08"",

    "source":{
        "funding_source_type": "S",
        "funding_source_id": "crd_c7015aecb8a05618",

        "currency_id": "USD",

        "currency_amount": "10.0000",
        "fee_amount": "3.0000",
        "total_payable": "13.0000",
    },

    "destination":{
        "recipient_bank_account_type": null,
        "recipient_bank_account_number": null,

        "currency_id": "COP",

        "net_receivable_in_source_currency": "10.0000",
        "exchange_rate": "2700.0000",
        "total_receivable": "27000.0000",
    },
}

Catalogs APIs

Catalog APIs provide informative data to perform a remittance transaction.

List supported Countries

A list of countries where remittance is supported.

GET /remittances/catalogs/countries

Arguments

Parameter	Type	Details
purpose	optional	By default purpose is NO.

Possible values for purpose can be:

NO: New Order. Filter values for transaction destinations
RS: Register Sender. Filter information for new sender registration
CB: Country of Birth. Filter information valid for personal profile

Get Details of a country

Details for a given country.

GET /remittances/catalogs/countries/[country_id]

List supported States of a country

Returns a list of supported states of specified country.

GET /remittances/catalogs/countries/[country_id]/states

Arguments

Parameter	Type	Details
purpose	optional	By default purpose is NO.

Possible values for purpose can be:

NO: New Order. Filter values for transaction destinations
RS: Register Sender. Filter information for new sender registration
CB: Country of Birth. Filter information valid for personal profile

List supported Cities of a country

Returns a list of supported cities of specified country.

GET /remittances/catalogs/countries/[country_id]/cities

Arguments

Parameter	Type	Details
state_id	optional	ID of supported state to filter the results further.
purpose	optional	By default purpose is NO.

Possible values for purpose can be:

NO: New Order. Filter values for transaction destinations
RS: Register Sender. Filter information for new sender registration
CB: Country of Birth. Filter information valid for personal profile

List supported KYC Photo Types for a Country

Returns a list of supported Identification Type/Photo ID for a given country. Identification Type/Photo ID is a type of identity document used for cardholder verification. For example, passport, travel document, national identity card etc. So, this method specifies which type of identity document is supported by a country for verification.

GET /remittances/catalogs/countries/[country_id]/kyc-photo-types

Get Assessed Exchange Rate for a country

Returns approximate exchange rate from source country to destination country. However, exact exchange rate depends upon which acquirer network and payment mode is selected for transaction.

GET /remittances/catalogs/countries/[country_id]/assessed-exchange-rate

Arguments

Parameter	Type	Details
currency_type	optional	ID of Currency Type either N=National or D=Dollar. N is default and recommended.

List supported Payment Modes

Returns a list of supported payment modes in specified country.

GET /remittances/catalogs/countries/[country_id]/payment-modes

Arguments

Parameter	Type	Details
city_id	optional	ID of supported city of specified country whose payment locations are to be fetched.
currency_type	optional	ID of Currency Type either N=National or D=Dollar. N is default and recommended.

List supported Payment Currencies

Returns a list of payment currencies that are supported in specified country.

GET /remittances/catalogs/countries/[country_id]/payment-currencies

Arguments

Parameter	Type	Details
city_id	optional	ID of supported city of specified country whose payment locations are to be fetched.

List supported Payment Networks

Returns a list of supported payment networks in specified country and specified payment mode.

GET /remittances/catalogs/countries/[country_id]/payment-modes/[payment_mode]/payment-networks

Arguments

Parameter	Type	Details
payment_mode	required	Mechanism of Receiving Payment: C = Bank Deposit, D = Home Delivery, P = Cash Pickup
currency_type	optional	ID of Currency Type either N=National or D=Dollar. N is default and recommended.

List supported Payment Locations

Returns a list of payment locations in specified country, city and payment mode.

GET /remittances/catalogs/countries/[country_id]/payment-locations

Arguments

Parameter	Type	Details
city_id	required	ID of supported city of specified country whose payment locations are to be fetched.
payment_mode	required	Mechanism of Receiving Payment: C = Bank Deposit, D = Home Delivery, P = Cash Pickup
currency_type	optional	ID of Currency Type either N=National or D=Dollar. N is default and recommended.
payment_network_id	optional	ID of acquirer/payment network for further filtration. Priority will be given to this field to show the results.

Sender APIs

Sender is the cardholder who initiates the remittance.

Create Sender Profile

Creates a new sender profile, based on the provided attributes, and returns a newly created Sender Object with unique Sender ID.

 POST /remittances/senders

Arguments

Parameter	Type	Details
first_name	required	First name of sender
middle_name	optional	Middle name of sender
last_name	required	Last name of sender
email	required	Sender’s Email
address1	required	Address of sender
address2	optional	Address of sender
phone1	required	Primary phone number of sender
phone2	optional	Secondary phone number of sender
country_id	required	ID of Country from where sender belongs
state_id	required	ID of State from where sender belongs
city_id	required	ID of City from where sender belongs
zip_code	required	Zip/Postal Code of sender’s area
photo_id_country	optional	ID of the Country which issued photo ID
photo_id_type	optional	Type of photo ID
photo_id	optional	Photo ID number
birth_date	optional	Sender’s Date of Birth
country_of_birth	optional	Name of the country where sender was born
external_uid	optional	User ID of the service consuming remittance module e.g. for Apto User: crdhldr_hw34hd3h

Get Sender Profile

Returns sender’s profile.

GET /remittances/senders/[sender_id]

Arguments

Parameter	Type	Details
type	optional	type=external; specifies that the given sender_id is the User ID of external service that is consuming the remittance module

Update Sender Profile

Updates basic information of a sender’s profile and returns updated sender object.

PUT /remittances/senders/[sender_id]

Recipient APIs

A recipient is someone to whom the funds are remitted. Cardholder/Sender will create profiles of receivers' to whom the funds are sent to.

List Recipients of a Sender

Returns a list of recipients for given sender/cardholder.

GET /remittances/senders/[sender_id]/recipients

Create Recipient Profile

Creates a new recipient for given sender/cardholder and returns newly created Recipient object.

POST /remittances/recipients

Arguments

Parameter	Type	Details
sender_id	required	ID of sender whose sender is to be created.
first_name	required	First name of sender
middle_name	optional	Middle name of sender
last_name	required	Last name of sender
address1	required	Address of sender
address2	optional	Address of sender
phone1	required	Primary phone number of sender
phone2	optional	Secondary phone number of sender
country_id	required	ID of Country from where sender belongs
state_id	required	ID of State from where sender belongs
city_id	required	ID of City from where sender belongs
zip_code	optional	Zip/Postal Code of sender’s area
email	optional	Sender’s Email

Get Recipient Profile

Returns the recipient object.

GET /remittances/recipients/[recipient_id]

Update Recipient Profile

Updates relevant recipient with provided information.

PUT /remittances/recipients/[recipient_id]

Delete Recipient Profile

Deletes the selected recipient and returns deleted object.

DELETE /remittances/recipients/[recipient_id]

Recipient Bank Account APIs

Before performing a remittance transaction, this is where we add the recipients' bank account information in order to use those accounts for transfers.

Attach Bank Account of a Recipient

Adds recipient's bank account information to avoid adding the same details over and over while performing transactions afterwards.

POST /remittances/recipients/[recipient_id]/bank-accounts

Arguments

Parameter	Type	Details
recipient_id	required	ID of the recipient whose bank account is to be added
routing_number	required	Routing number of recipient’s bank account
bank_account_number	required	Recipient’s bank account number
bank_account_type	required	Type of Bank Account either C = Checking or S = Saving
payment_network_id	required	ID of the relevant acquirer/bank to which bank account belongs
nick_name	required	A nickname to identify account in bank accounts’ list

Get an attached bank account

Returns recipient’s bank account object given the relevant sender, recipient and bank account IDs.

GET /remittances/recipients/[recipient_id]/bank-accounts/[bank_account_id}

List all attached bank accounts

Returns a list of bank accounts of specific recipient.

GET /remittances/recipients/[recipient_id]/bank-accounts

Update an attached bank account

Updates given information of recipient’s bank account and returns updated object of recipient’s bank account.

PUT /remittances/recipients/[recipient_id]/bank-accounts/[bank_account_id}

Detach Bank Account of a Recipient

Deletes given bank account profile of recipient and returns deleted object.

DELETE /remittances/recipients/[recipient_id]/bank-accounts/[bank_account_id}?sender_id=[sender_id]

Remittance Transaction APIs

Get Transaction Cost Model

Returns applicable fees and costs for a transaction for given payment mode and payment network.

GET /remittances/catalogs/payment-modes/[payment_mode]/payment-networks/[payment_network_id]/cost-model

Arguments

Parameter	Type	Details
payment_mode	required	ID of payment mode. C = Bank Deposit, D = Home Delivery, P = Cash Pickup
payment_network_id	required	ID of payment/acquirer network through which remittance is to be made.
amount	required	Net Amount which is to be sent e.g. 1118.27
funding_source_type	required	Sender’s funding source ID. S=Apto Card
currency_type	optional	ID of Currency Type either N = National or D = Dollar. N is default and recommended.

Create Remittance Transaction

Creates transaction and returns the transaction details. To create a remittance transaction, specify the payment mode and the network that supports specified payment mode. Then provide recipient's info as per specified payment mode.

POST /remittances/senders/[sender_id]/transactions

Arguments

Parameter	Type	Details
payment_mode	required	ID of payment mode. C = Bank Deposit, D = Home Delivery, P = Cash Pickup
recipient_id	required	ID of the recipient to whom transaction is to be sent. Either recipient_id is required otherwise, all fields relevant to recipient are required.
country_id	required	ID of the country where transaction is to be sent.
state_id	optional	ID of the state where transaction is to be sent.
city_id	optional	ID of the city where transaction is to be sent.
payment_location_id	required	ID of the acquirer location where transaction is to be sent.
first_name	required	Recipient’s first name
middle_name	optional	Recipient’s middle name
last_name	required	Recipient’s last name
address	required	Recipient’s address
phone	required	Recipient’s phone number
payment_mode	required	Mechanism of Receiving Payment: C = Bank Deposit, D = Home Delivery, P = Cash Pickup
amount	required	Net amount to be sent in transaction
bank_account_id	required	"ID of Recipient’s bank account added by current sender. If supplied, bank info will be fetched from it. Either bank_account_id or bank_account_number is required at a time."
bank_account_number	required	Recipient’s bank account number where transaction is to be sent. Needed only if Payment Mode is Bank Deposit i.e. payment_mode = C. Not required when providing bank_account_id.
bank_account_type	required	ID of Recipient’s bank account type: C=Checking, S=Saving. Not required when providing bank_account_id. However, required along bank_account_number.
idempotency_key	required	A random key generated by client and sent to server for integrity and fault tolerance whenever a transaction is to be created.
funding_source_type	required	Sender’s funding source ID. S=Apto Card
funding_source_id	required	ID of sender’s funding source which could be sender’s Bank Account ID or Card ID
idempotency_key	required	An idempotency key to ensure integrity of requests
currency_type	optional	ID of Currency Type either N = National or D = Dollar. N is default and recommended.

Possible Status for a transaction can be:

H: Hold
I: Pending to transmit to network
T: Transmitted to network
P: Payed
A: Abandoned

Get details of a Remittance Transaction

Returns details of a transaction given specific sender and transaction IDs.

GET /remittances/senders/[sender_id]/transactions/[transaction_id}

List Remittance Transactions

Returns a list of recent transactions for a given sender/cardholder.

GET /remittances/senders/[sender_id]/transactions

shahid-ccs/apto-api-specs.md

Apto API

Guide

Integration Options

Lay of the land

Errors

Cardholders

Know Your Customer

Create a cardholder

Update a cardholder

Retrieve a cardholder

List all cardholders

Cardholder Cards

Create a cardholder card

Cardholder Transactions

Create a cardholder transaction (testmode only)

List all cardholder transactions

Cardholder Balances

Retrieve a cardholder balances

Retrieve cardholder current balance

Cards

Retrieve a card

Wallet lifecycle

Change card PIN

Change card status

List all card transactions

Order Physical Card

Activate physical card

Card Balances

Retrieve a card balance

Debit balance on card

Credit balance on card

Card Batches

Create Bulk Cards

Card Batches lifecycle

Retrieve a Card Batch Details

Cancel Card Batch

Transactions

Retrieve a transaction

List all transactions

Webhooks

KYC Status Updates

Card Updates

Daily Settlement

Transaction Updates

Card Batch Updates

Remittances

API Objects

Country

State

City

KYC Photo Type

Assessed Exchange Rate

Payment Network

Payment Location

Payment Mode

Payment Currency

Cost Model

Sender

Recipient

Recipient Bank Account

Remittance Transaction

Catalogs APIs

List supported Countries

Get Details of a country

List supported States of a country

List supported Cities of a country

List supported KYC Photo Types for a Country

Get Assessed Exchange Rate for a country

List supported Payment Modes

List supported Payment Currencies

List supported Payment Networks

List supported Payment Locations

Sender APIs

Create Sender Profile

Get Sender Profile

Update Sender Profile

Recipient APIs

List Recipients of a Sender

Create Recipient Profile