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

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

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.

Responses

application/json

Schema
Example (from schema)
Example

Schema

prerequisites

object[]

Array [

stage string

Possible values: [funding, kyc, aml]

status string

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

type string

Possible values: [smart_contract_write, kyc, aml-review, contact_email, contact_phone, simulator_call, expected_spend_amount]

actionType string

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

smart_contract_write
kyc
contact_email
contact_phone
simulator_call

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

status string

Possible values: [check_in_progress, kyc_required, kyc_check_failed]

The cardholder's KYC status.

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

reasons

object[]

List of the reasons for the failed KYC check

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, UNKNOWN]

Code of the failed check

description string

Human readable description of the failed check

]

kycUrl string

A URL for the KYC process (if conducted by Immersve)

status string

Possible values: [missing]

The cardholder's contact email is missing and needs to be added.

status string

Possible values: [missing]

The cardholder's contact phone is missing and needs to be added.

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.

]

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

statusName stringrequired

errorCode stringrequired

errors string[]

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