Get Spending Prerequisites
POST/api/spending-prerequisites
This endpoint specifies the necessary prerequisites that must be met for a cardholder to successfully create a card and transact with it against a specified Funding Source. The caller can specify the desired spend and receive the necessary transactions required, accounting for existing deposits, to deposit funds on-chain to meet that spend. It includes any KYC and AML requirements.
Request
- application/json
Body
required
ID of card program to create the card under
ID of the Funding Source the card will authorize against
Amount of fiat money that should be available on the card, denominated in minor units
Possible values: [USD
]
Currency to be used when creating the card. Currently only supports USD
Possible values: [immersve-conducted
, partner-conducted
]
Type of KYC depending on which party is conducting it
A URL to which the user can be redirected after they have completed or exited the kyc process.
Responses
- 200
- 400
- 403
- application/json
- Schema
- Example (from schema)
- Example
Schema
Array [
- smart_contract_write
- kyc
- contact_email
- contact_phone
- simulator_call
Array [
Array [
]
]
- check_in_progress: KYC check is in progress, request spending prerequisites again later
- kyc_required: KYC is required, initiate the process by submitting a KYC statement and requesting spending prerequisites
- kyc_check_failed: KYC check failed, check the submitted KYC statement and retry the process or contact support
]
prerequisites
object[]
Possible values: [funding
, kyc
, aml
]
Possible values: [action-required
, pending
, blocked
, ok
]
Possible values: [smart_contract_write
, kyc
, aml-review
, contact_email
, contact_phone
, simulator_call
, expected_spend_amount
]
Possible values: [smart_contract_write
, submit_contact_email
, submit_contact_phone
, follow_kyc_url
, submit_kyc_statement
, aml-review
, set_expected_spend_amount
]
params
object
oneOf
The address of the smart contract
abi
object[]
The JSON ABI of the smart contract (contains only required details. more details here https://docs.soliditylang.org/en/v0.8.19/abi-spec.html#json)
Possible values: [function
]
The name of the function
inputs
object[]
The name of the parameter
The type of the parameter
Smart contract method
Smart contract call params. Keys are matching names and order defined in ABI
Possible values: [check_in_progress
, kyc_required
, kyc_check_failed
]
The cardholder's KYC status.
A URL for the KYC process (if conducted by Immersve)
Possible values: [missing
]
The cardholder's contact email is missing and needs to be added.
Possible values: [missing
]
The cardholder's contact phone is missing and needs to be added.
The payload
instructions should be send to this URL using an HTTP POST.
payload
object
The payload with the instructions for the deposit.
The simulated deposit amount in minor units of the funding source token.
The funding source to deposit funds to.
{
"prerequisites": [
{
"stage": "funding",
"status": "action-required",
"type": "smart_contract_write",
"actionType": "smart_contract_write",
"params": {}
}
]
}
{
"prerequisites": [
{
"stage": "funding",
"status": "action-required",
"type": "smart_contract_write",
"actionType": "smart_contract_write",
"params": {
"abi": [
{
"constant": false,
"inputs": [
{
"name": "_spender",
"type": "address"
},
{
"name": "_value",
"type": "uint256"
}
],
"name": "approve",
"outputs": [
{
"name": "",
"type": "bool"
}
],
"payable": false,
"stateMutability": "nonpayable",
"type": "function"
}
],
"contractAddress": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
"method": "approve",
"params": {
"_spender": "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512",
"_value": "1000000"
}
}
},
{
"stage": "funding",
"status": "action-required",
"type": "smart_contract_write",
"actionType": "smart_contract_write",
"params": {
"abi": [
{
"inputs": [
{
"internalType": "uint256",
"name": "_amount",
"type": "uint256"
}
],
"name": "depositAndLock",
"outputs": [],
"stateMutability": "nonpayable",
"type": "function"
}
],
"contractAddress": "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512",
"method": "depositAndLock",
"params": {
"_amount": "1000000"
}
}
},
{
"stage": "kyc",
"status": "action-required",
"type": "kyc",
"actionType": "follow_kyc_url",
"params": {
"status": "kyc_required",
"kycUrl": "https://verify.immersve.com"
}
},
{
"stage": "kyc",
"status": "action-required"
"type": "contact_email",
"actionType": "submit_contact_email",
"params": {
"status": "missing"
}
},
{
"stage": "kyc",
"status": "action-required",
"type": "contact_phone",
"actionType": "submit_contact_phone",
"params": {
"status": "missing"
}
},
{
"stage": "aml",
"status": "pending",
"params": {}
},
{
"stage": "kyc",
"status": "action-required",
"type": "expected_spend_amount",
"actionType": "set_expected_spend_amount",
}
]
}
Request fields are invalid
- application/json
- Schema
- Example (from schema)
Schema
{
"statusCode": 400,
"statusName": "Bad Request",
"errorCode": "BAD_REQUEST",
"errors": [
"Expected string, received number"
]
}
User is not allowed to perform the action with the reason stated in the errorCode
FORBIDDEN Insufficient permissions to perform the action.
LIVENESS_MISMATCH Resource liveness does not match request liveness.
CARD_PROGRAM_INVALID Card program does not belong to a partner this cardholder is associated with.
FUNDING_SOURCE_INVALID Funding source cannot be used with this card program.
KYC_PROFILE_REGION_MISMATCH The KYC profile is already approved for a region different from the requested region. Use the Get KYC Profile endpoint to determine the current region of the KYC profile.
UNSUPPORTED_KYC_REGION The KYC region is not yet supported.
KYC_STATEMENT_REGION_MISMATCH The latest unchecked KYC statement is for a region that is different from the requested region.
- application/json
- Schema
- Example (from schema)
Schema
{
"statusCode": 403,
"statusName": "Forbidden",
"errorCode": "FORBIDDEN",
"reason": "Unauthorized"
}