Get 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.

application/json

Request Body required

• cardProgramId string required

  ID of card program to create the card under

• fundingSourceId string required

  ID of the Funding Source the card will authorize against

• spendableAmount string required

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

• spendableCurrency string required

  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.

• kycRegion string

  An Alpha3 (ISO-3166-1) country code representing the country in which the user is being KYC'd.

Responses

• 200
• 400
• 403

---

application/json

• Schema
• Example (from schema)
• Example

---

Schema

• prerequisites object[]

  Array [

  type string

  Possible values: [smart_contract_write, kyc, contact_email, contact_phone]

  params object

  oneOf

  • smart_contract_write
  • kyc
  • contact_email
  • contact_phone

  ---

  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

  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.

• ]

{
  "prerequisites": [
    {
      "type": "smart_contract_write",
      "params": {
        "contractAddress": "string",
        "abi": [
          {
            "type": "function",
            "name": "approve",
            "inputs": [
              {
                "name": "_spender",
                "type": "address"
              }
            ]
          }
        ],
        "method": "string",
        "params": {}
      }
    }
  ]
}

{
  "prerequisites": [
    {
      "type": "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"
        }
      }
    },
    {
      "type": "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"
        }
      }
    },
    {
      "type": "kyc",
      "params": {
        "status": "kyc_required",
        "kycUrl": "https://verify.immersve.com"
      }
    },
    {
      "type": "contact_email",
      "params": {
        "status": "missing"
      }
    },
    {
      "type": "contact_phone",
      "params": {
        "status": "missing"
      }
    }
  ]
}

Request fields are invalid

application/json

• Schema
• Example (from schema)

---

Schema

• statusCode integer required
• statusName string required
• errorCode string required
• 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_CARD_PROGRAM_REGION_MISMATCH The card program and the KYC profile are not is the same region.

AML_CHECK_FAILED AML check failed. This cannot be resolved.

UNSUPPORTED_KYC_REGION The KYC region is not yet supported.

application/json

• Schema
• Example (from schema)

---

Schema

• statusCode integer required
• statusName string required
• errorCode string required
• reason string

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