---
title: "Submit Receive Request"
method: POST
path: "/receive"
---

# Submit Receive Request

`POST /receive`

Submit a receive request. This will lock in a rate and await approval.

## Request body

- object
  - `channelId` string, required — The identifier of the specific channel to execute payment through
  - `sequenceId` string, required — Represents a unique id for the transaction from your end
  - `amount` integer — Amount in USD to transact
  - `localAmount` integer — The amount in local currency to transact
  - `recipient` object — Recipient's KYC details
    - `name` string — Recipient's full name. Required only if `customerType` is retail.
    - `country` string — Recipient's country in ISO 3166 format. Example, NG, CM, GH. https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes. Required only if `customerType` is retail.
    - `address` string — Recipient's address. Required only if `customerType` is retail.
    - `dob` string — Recipient's date of birth (mm/dd/yyyy). Required only if `customerType` is retail.
    - `email` string — Recipient's email address. Required for both `customerType` is `retail` and `institution`.
    - `idNumber` string — Recipient's ID number. Required only if `customerType` is retail.
    - `idType` string — Recipient's identity document type. Required only if `customerType` is retail.
    - `additionalIdType` string — Recipient's additional ID type. Required only if `customerType` is retail and recipient country is NG
    - `additionalIdNumber` string — Recipient's additional ID number. Required only if `customerType` is retail and recipient country is NG
    - `phone` string — Recipient's phone number. Required only if `customerType` is retail.
    - `businessId` string — Recipient's business id. Required only if `customerType` is institution.
    - `businessName` string — Recipient's business name. Required only if `customerType` is institution.
  - `source` object — Source account details
    - `accountType` string, required — The type of account ('bank' or 'momo')
    - `accountNumber` string — For momo account type, Mobile money phone number of the Recipient. In the sandbox environment use 1111111111 simulate a success source and 0000000000 for a failure source for both "momo" and "bank". Please note that the account number is not required for bank receives in production
    - `networkId` string — The identifier of the specific network to execute payment through (not required for bank receives)
  - `forceAccept` boolean — Specify whether or not you want to skip the accept collection step
  - `customerType` 'retail' | 'institution', required — Determines the type of validation that is performed on the recipient. If value is `institution`, the recipient request object will be validated to ensure it includes `businessName` and `businessId` parameter. If the value is `retail`, the recipient request object will be validated to ensure it includes `name`, `phone`, `email`, `country`, `address`, `dob`, `idNumber` and `idType`
  - `redirectUrl` string — This is used to determine where the customer is redirected to after a transaction is initiated for channels that require redirect. This param is required if the selected channel requires redirect and forceAccept is set to true.
  - `customerUID` string, required — Unique identifier for the customer
  - `country` string — Country ISO 3166 code e.g. NG, KE, CI. This field is only required when using `channelType`
  - `currency` string — Currency code e.g. NGN, KES, XAF, XOF. This field is only required when using `channelType`
  - `channelType` 'bank' | 'momo'
  - `directSettlement` boolean
  - `settlementInfo` object — Only required when `directSettlement` is true
    - `walletAddress` string — Crypto payout destination wallet address
    - `cryptoCurrency` string — USDC, USDT, CUSD, etc.
    - `cryptoNetwork` string — SOL, ERC20, TRC20
    - `walletTag` string — only required for USDC - XLM destination addresses

## Response `200`

200

- object
  - `recipient` object
    - `name` string
    - `country` string
    - `phone` string
    - `address` string
    - `dob` string
    - `email` string
    - `idNumber` string
    - `idType` string
  - `source` object
    - `accountNumber` string
    - `accountType` string
    - `networkId` string
  - `channelId` string
  - `sequenceId` string
  - `amount` integer
  - `currency` string
  - `country` string
  - `partnerId` string
  - `apiKey` string
  - `id` string
  - `status` string
  - `convertedAmount` integer
  - `rate` number
  - `expiresAt` string
  - `createdAt` string
  - `updatedAt` string

## Other responses

- `400` — 400
- `500` — 500

---

[API](https://skmtc.net/yellowcard/apis/yellow-cards-payment-api.md) · [All operations](https://skmtc.net/yellowcard/apis/yellow-cards-payment-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yellowcard/yellow-cards-payment-api/versions/516d251059cc/schema)