Get Spending Prerequisites

POST /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

cardProgramId stringrequired

ID of card program to create the card under

fundingSourceId stringrequired

ID of the Funding Source the card will authorize against

spendableAmount stringrequired

Amount of fiat money that should be available on the card, denominated in minor units

spendableCurrency stringrequired

Possible values: [USD]

Currency to be used when creating the card. Currently only supports USD

fundingMode string

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.

kycType string

Possible values: [immersve-conducted, partner-conducted]

Type of KYC depending on which party is conducting it

kycRedirectUrl string

A URL to which the user can be redirected after they have completed or exited the kyc process.

kycRegion string

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.

kycHiddenSteps array

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

application/json

Schema
Example (from schema)
Example

Schema

prerequisites

object[]

Array [

anyOf

Funding Instruction
KYC Instruction
AML Instruction

stage required

Possible values: [funding]

status required

Possible values: [action-required, pending, blocked, ok]

actionType

Possible values: [smart_contract_write, simulator_call]

type stringdeprecated

The prerequisite instruction type. This attribute is deprecated. Clients should use stage and actionType instead.

params

object

The parameters for the prerequisite instruction, if applicable. Specific parameters vary based on the prerequisite instruction's action type.

oneOf

Smart Contract Write Params
Simulator Call Params

contractAddress string

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)

Array [

type string

Possible values: [function]

name string

The name of the function

inputs

object[]

Array [

name string

The name of the parameter

type string

The type of the parameter

]

method string

Smart contract method

params object

Smart contract call params. Keys are matching names and order defined in ABI

url string

The payload instructions should be send to this URL using an HTTP POST.

payload

object

The payload with the instructions for the deposit.

amount string

The simulated deposit amount in minor units of the funding source token.

fundingSourceId string

The funding source to deposit funds to.

stage required

Possible values: [kyc]

status required

Possible values: [action-required, pending, blocked, ok]

actionType

Possible values: [submit_contact_email, submit_contact_phone, follow_kyc_url, submit_kyc_statement, set_expected_spend_amount, submit_residential_addresses]

type stringdeprecated

The prerequisite instruction type. This attribute is deprecated. Clients should use stage and actionType instead.

params

object

The parameters for the prerequisite instruction, if applicable.

kycUrl string

A one-time, secure URL for redirecting the cardholder to the Immersve-conducted KYC user experience.

ctaHint string

Possible values: [KYC_NOT_STARTED, KYC_NOT_COMPLETED, KYC_INFORMATION_NEEDED, KYC_EXPIRING]

Hint for supplying a meaningful call-to-action to the cardholder explaining why action is needed.

reasons

object[]

List of specific reasons why a KYC action is required. These coded reasons can be used to help prompt users for more information when KYC background checks have failed.

Array [

code string

Possible values: [ID_NOT_VERIFIED, NAME_NOT_VERIFIED, ADDRESS_NOT_VERIFIED, DOB_NOT_VERIFIED, DOB_OR_ADDRESS_NOT_VERIFIED, VISA_NOT_FOUND, BIOMETRICS_FAILED, PROFILE_LIMIT_REACHED, SUSPENDED, UNKNOWN]

KYC action reason code.

description string

Human readable reason description.

]

status stringdeprecated

Possible values: [check_in_progress, kyc_required, kyc_check_failed]

The cardholder's KYC status. This attribute is deprecated. Clients should use the prerequisite status field to detect when checks are in progress, the ctaHint field to determine why action is required, and the params reasons field to detect when or why KYC checks have failed.

stage

Possible values: [aml]

status

Possible values: [pending, blocked, ok]

type stringdeprecated

The prerequisite instruction type. This attribute is deprecated. Clients should use stage instead.

]

{
  "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

statusCode integerrequired

statusName stringrequired

errorCode stringrequired

errors

object[]

Array [

message string

path string

The location of the invalid path param, query param or payload attribute.

]

{
  "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 integerrequired

statusName stringrequired

errorCode stringrequired

reason string

{
  "statusCode": 403,
  "statusName": "Forbidden",
  "errorCode": "FORBIDDEN",
  "reason": "Unauthorized"
}

Get Spending Prerequisites

/api/spending-prerequisites

Request​

Body

Responses​

Request

Responses