Get Spending Prerequisites
POSThttps://api.immersve.com/api/spending-prerequisites
Check for outstanding cardholder "Spending Prerequisites". Clients should use the returned prerequisite instructions to guide the user through the card onboarding user journey.
Spending prerequisites are divided into three stages: Funding, KYC, and AML. When each of these three stages indicate the status is "ok" then the cardholder can proceed to transact with their card.
See the KYC Spending Prerequisites guide for more details about how to consume the prerequisite instructions for your cardholder onboarding experience.
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: [deposit
, approval
]
Hint for the prerequisite funding transaction type. Presently only universal-evm funding supports the funding mode hint.
deposit
(default) — Funding instruction should be a token transfer.
approval
— Funding instruction should be a token approval.
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.
The country in which the user resides, in two letter country code format (e.g. AU
). This must be one of the countries enabled in the card program for your partner account.
Note - this is only required when using the kycHiddenSteps
option to hide the region KYC step.
Possible values: [region
, expected-spend
, contact-channels
, residential-address
]
A list of KYC steps to skip in the Immersve Conducted UI. Cardholder information for these steps must be provided separately via API.
Responses
- 200
- 400
- 403
- application/json
- Schema
- Example (from schema)
- Example
Schema
prerequisites
object[]
{
"prerequisites": [
{},
{},
{}
]
}
{
"prerequisites": [
{
"stage": "funding",
"status": "action-required",
"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": "kyc",
"status": "action-required",
"actionType": "follow_kyc_url",
"params": {
"kycUrl": "https://verify.immersve.com"
"reasons": [{
"code": "ADDRESS_NOT_VERIFIED"}],
"message": "Residential Address could not be matched in the required number of databases"
}]
}
},
{
"stage": "kyc",
"status": "action-required"
"actionType": "submit_contact_email",
},
{
"stage": "kyc",
"status": "action-required",
"actionType": "submit_contact_phone",
},
{
"stage": "kyc",
"status": "action-required",
"actionType": "set_expected_spend_amount",
},
{
"stage": "aml",
"status": "pending",
}
]
}
Request fields are invalid
- application/json
- Schema
- Example (from schema)
Schema
errors
object[]
{
"statusCode": 400,
"statusName": "Bad Request",
"errorCode": "INVALID_REQUEST_INPUT",
"errors": [
{
"message": "Invalid type",
"path": "items[1].attributes.invalidField"
}
]
}
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"
}
- curl
- python
- go
- nodejs
- ruby
- csharp
- php
- java
- powershell
- CURL
curl -L 'https://api.immersve.com/api/spending-prerequisites' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-d '{
"cardProgramId": "string",
"fundingSourceId": "string",
"spendableAmount": "string",
"spendableCurrency": "USD",
"fundingMode": "deposit",
"kycType": "immersve-conducted",
"kycRedirectUrl": "string",
"kycRegion": "string",
"kycHiddenSteps": [
null
]
}'