KYC/KYB endorsements

Learn how to use KYC endorsement endpoints to unlock gated virtual account channels, including USD virtual accounts for business users.

Use endorsements to unlock gated channels when an already onboarded and KYC-approved user needs an additional eligibility check, including virtual accounts and BRL pay-ins and payouts.

📘

For all statuses and how to handle them with webhooks, see Onboarding & compliance lifecycle.

Endorsement codes

Check endorsementsRequired on the target channel and follow the linked guide for its requirements.

Endorsement codeGuideUse
usd_pr_bank_v1Zenus USD virtual account endorsementUSD virtual accounts on ach, wire, and swift for individual and business accounts, with a 5,000,000 USD limit.
eur_va_named_v1EUR named virtual account endorsementOptional named receiving details for newly created EUR virtual accounts.
gbp_bank_v1GBP bank virtual account endorsementGBP bank virtual accounts.
aud_bank_v1AUD bank virtual account endorsementAUD bank virtual accounts.
aed_bank_v1AED bank virtual account endorsementAED bank virtual accounts.
brl_bank_v1BRL bank virtual account endorsementRequired for all BRL PIX pay-ins, virtual accounts, and payouts.

No BRL channel is available until brl_bank_v1 is approved. BR residents receive virtual account details in their own name and can use first-party-only pay-ins and payouts; non-BR residents receive details in Due's name and can use first- and third-party pay-ins and payouts. These rules apply to individuals and businesses. Third-party payments for BR residents are available on request, subject to approval. See BRL bank virtual account endorsement for details.

When to use this flow

Use this flow when:

  • The user is already onboarded.
  • The user has successfully completed standard KYC/KYB.
  • The user or platform wants to create a specific virtual account that needs extra info.
  • The target channel requires one or more endorsements.

Endorsements are additional checks required by specific channels. A gated channel exposes the endorsement codes it requires. You request those endorsements for the account before creating the virtual account.

Optional: EUR named virtual accounts

Use the EUR named virtual account endorsement when an account needs newly created EUR virtual accounts to use named receiving details.

Request this endorsement with the code:

eur_va_named_v1
curl --request POST \
  --url https://api.sandbox.due.network/v1/kyc/endorsements/eur_va_named_v1 \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Due-Account-Id: acct_DqvgNSAuQv5OEK9v'

After requesting the endorsement, wait for the endorsement approval webhook before creating EUR virtual accounts that should be named. EUR virtual accounts created after the endorsement is approved are named.

This endorsement is not required to create EUR virtual accounts. If the account does not have the eur_va_named_v1 endorsement, EUR virtual accounts can still be created, but they are created as non-named virtual accounts.

For dashboard clients, this endorsement is not currently discoverable in the dashboard. Share and trigger the endorsement manually when a client needs EUR named virtual accounts.

Sandbox named behavior may need to be simulated for testing. Confirm sandbox setup before testing this flow.

Expected flow

  1. List available channels.
  2. Check whether the desired channel requires endorsements - endorsementsRequiredfield.
  3. Request each required endorsement code for the account.
  4. Check whether the endorsement response created a new submission.
  5. If extra information is required, complete the new submission.
  6. Wait for endorsement.status_changed with status: approved. Additional information arrives as information requests.
  7. Create the virtual account.

Prerequisites

Before you start:

  1. Complete the user’s onboarding.

  2. Complete the user’s standard KYC/KYB flow.

  3. Store the account ID, for example:

    acct_DqvgNSAuQv5OEK9v
  4. Use the account ID in the Due-Account-Id header for all account-scoped KYC/KYB and endorsement requests.

  5. Check the channel requirements


Endorsement codes are defined on channels.

When a channel is gated, the channel configuration contains the list of required endorsements. For example, the USD virtual account channel requires this endorsement code:

usd_pr_bank_v1

The same code applies to individual and business accounts for ach, wire, and swift virtual accounts, with a 5,000,000 USD limit.

Retrieve all enabled payment channels with their specifications and pricing and search for your desired channel, then look for the endorsement field, endorsementsRequired.

GET /v1/channels
{
    "rail": "ach",
    "railSettings": {
        "rail": "ach",
        "speed": "1-2 days",
        "memoConfig": {
            "minCharacters": 0,
            "maxCharacters": 10,
            "required": false
        },
        "schemas": [
            "bank_us"
        ]
    },
    "currencyCode": "USD",
    "feeBps": 20,
    "feeFixed": "20",
    "limitMin": "1.5",
    "limitMax": "5000000",
    "kycLevels": [],
    "type": "static_deposit",
    "accountType": "business",
    "permissions": {
        "restrictedResidencies": [
            "US"
        ],
        "restrictedCategories": [
            "gambling"
        ]
    },
    "purposeCodes": {},
    "endorsementsRequired": [
        "usd_pr_bank_v1"
    ]
}

2. Request the endorsement

Request each endorsement required by the channel.

Store the response. Its informationRequests[] and their submissions are not announced by webhook.

curl --request POST \
  --url https://api.sandbox.due.network/v1/kyc/endorsements/usd_pr_bank_v1 \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Due-Account-Id: acct_DqvgNSAuQv5OEK9v'

Replace:

ValueDescription
<API_KEY>Your Due API key.
acct_DqvgNSAuQv5OEK9vThe account ID that needs access to the gated channel.
usd_pr_bank_v1The endorsement code required for USD virtual accounts.

3. Execute the endorsement

The endorsement response tells you whether additional information is required.

If no extra information is required, the endorsement can continue without opening a new data collection step.

If extra information is required, the response includes a new KYC/KYB submission.

Example response:

{
  "ownerId": "acct_DqvgNSAuQv5OEK9v",
  "code": "usd_pr_bank_v1",
  "status": "requested",
  "submission": {
    "id": "ksub_i11Sowou6GxhBRux",
    "ownerId": "acct_DqvgNSAuQv5OEK9v",
    "applicantId": "ka_TQIIfHqJ86nsoWU4",
    "status": "open",
    "info": {},
    "requirements": [
      {
        "kind": "static",
        "info": [
          { "key": "companyName", "type": "string" },
          { "key": "registrationNumber", "type": "string" },
          { "key": "registrationDate", "type": "date" },
          { "key": "taxId", "type": "string" }
        ],
        "documents": [
          { "category": "COMPANY_DETAILS", "oneOf": [{ "type": "INCORPORATION_CERT" }] },
          { "category": "COMPANY_CONTROL_STRUCTURE", "oneOf": [{ "type": "DIRECTORS_REGISTRY" }] },
          { "category": "COMPANY_AUTHORIZATION", "oneOf": [{ "type": "CORPORATE_RESOLUTION" }] },
          { "category": "TAX_REGISTRATION", "oneOf": [{ "type": "COMPANY_FISCAL_REG_CERT" }] },
          { "category": "TAX_COMPLIANCE", "oneOf": [{ "type": "FATCA" }] },
          { "category": "FINANCIAL_STATEMENTS", "oneOf": [{ "type": "FINANCIAL_STATEMENTS" }] },
          { "category": "PROOF_OF_ADDRESS", "oneOf": [{ "type": "PROOF_OF_ADDRESS" }] },
          { "category": "SOURCE_OF_FUNDS", "oneOf": [{ "type": "SOURCE_OF_FUNDS" }] },
          { "category": "TAX_IDENTIFICATION", "oneOf": [{ "type": "TAX_ID_NUMBER" }] }
        ]
      }
    ],
    "documents": [],
    "questionnaires": [],
    "presetCode": "usd_pr_bank_v1",
    "source": "api"
  }
}

For individual and business requirements, see Zenus USD virtual account endorsement.

4. Check whether a submission was created

Check the submission object in the endorsement response.

FieldDescription
ownerIdThe account that owns the endorsement.
codeThe endorsement code requested.
statusOne of requested, processing, awaiting_approval, approved, processing_error.
submission.idThe new submission ID created for missing information.
submission.statusThe submission status. An open submission requires action.
submission.requirementsThe information, documents, or questionnaire answers required for the endorsement.
submission.presetCodeThe endorsement code that created the submission.

If submission.status is open, collect and submit the required information before creating the virtual account.

5. Retrieve the submission by ID

Use the submission ID returned by the endorsement response.

curl --request GET \
  --url https://api.sandbox.due.network/v1/kyc/submissions/ksub_i11Sowou6GxhBRux \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Due-Account-Id: acct_DqvgNSAuQv5OEK9v'

The response shows the current submission state and the remaining requirements.

6. Complete the missing requirements

The endorsement submission uses the regular Due submission flow.

Depending on the requirements array, the account may need to provide:

  • Personal information, such as name, date of birth, phone, or nationality.
  • Company information, such as company name, registration number, registration date, or tax ID.
  • Identity documents, such as passport, ID card, or residence permit.
  • Company documents, such as incorporation, tax, authorization, financial statement, or source-of-funds documents.
  • A selfie.
  • Address information or proof of address.
  • Questionnaire answers, such as declarations for PEP, sanctions, or criminal convictions.

There are two supported ways to complete the submission:

  1. Submit the information through the API.
  2. Send the user through Due’s hosted submission flow.

7. Option A: Submit the required information through the API

Use the existing KYC submission endpoints to provide the required information, documents, and questionnaire answers.

The requirements array tells you what to submit.

For example, this USD virtual account business endorsement requirement means you need to provide four company information fields:

{
  "kind": "static",
  "info": [
    { "key": "companyName", "type": "string" },
    { "key": "registrationNumber", "type": "string" },
    { "key": "registrationDate", "type": "date" },
    { "key": "taxId", "type": "string" }
  ]
}

This requirement means you need to provide company documents for the listed categories:

{
  "kind": "static",
  "documents": [
    { "category": "COMPANY_DETAILS", "oneOf": [{ "type": "INCORPORATION_CERT" }] },
    { "category": "COMPANY_CONTROL_STRUCTURE", "oneOf": [{ "type": "DIRECTORS_REGISTRY" }] },
    { "category": "COMPANY_AUTHORIZATION", "oneOf": [{ "type": "CORPORATE_RESOLUTION" }] },
    { "category": "TAX_REGISTRATION", "oneOf": [{ "type": "COMPANY_FISCAL_REG_CERT" }] },
    { "category": "TAX_COMPLIANCE", "oneOf": [{ "type": "FATCA" }] },
    { "category": "FINANCIAL_STATEMENTS", "oneOf": [{ "type": "FINANCIAL_STATEMENTS" }] },
    { "category": "PROOF_OF_ADDRESS", "oneOf": [{ "type": "PROOF_OF_ADDRESS" }] },
    { "category": "SOURCE_OF_FUNDS", "oneOf": [{ "type": "SOURCE_OF_FUNDS" }] },
    { "category": "TAX_IDENTIFICATION", "oneOf": [{ "type": "TAX_ID_NUMBER" }] }
  ]
}

Some documents, such as the incorporation certificate, directors registry, or proof of address, may already have been collected during business onboarding or KYB. The endorsement submission remains the source of truth for what is still required.

After all required information has been provided, complete the submission using the regular submission completion endpoint.

8. Option B: Use the hosted submission flow

You can also use Due’s hosted solution to collect the missing information from the user.

Use this option if you do not want to collect and submit the required data directly through your own API integration.

circle-info

The endorsement submission uses Due’s hosted solution. Do not mix this up with Sumsub links from the standard KYC flow.

The hosted flow should be opened for the new submission created by the endorsement request.

Use the submission.id from the endorsement response:

ksub_i11Sowou6GxhBRux

The user completes the missing information in the hosted flow. After completion, the endorsement can continue processing.

Troubleshooting

The endorsement response does not include a link

POST /v1/kyc/endorsements/{code} does not return a Sumsub link.

If extra data is required, the response returns a Due submission object. Use that submission with either:

  • The regular KYC submission API flow, or
  • Due’s hosted submission flow.

The endorsement created a submission, but GET /v1/kyc/submissions does not show it

Use the submission ID returned by the endorsement response and retrieve it directly:

curl --request GET \
  --url https://api.sandbox.due.network/v1/kyc/submissions/ksub_i11Sowou6GxhBRux \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Due-Account-Id: acct_DqvgNSAuQv5OEK9v'

The submission cannot be found

Check the Due-Account-Id header.

The submission belongs to the account that requested the endorsement. If you use another account ID, the API may return a not found error.

Correct:

Due-Account-Id: acct_DqvgNSAuQv5OEK9v

Incorrect:

Due-Account-Id: <another_account_id>

The channel does not show an endorsement code

Endorsement codes are defined on channels.

If the channel does not include an endorsement requirement yet, there is no endorsement code to request for that channel. When the gated channel configuration is enabled, the channel will expose the required endorsement codes.

Summary

For gated virtual account channels, use this endorsement flow:

  1. Check the target channel for required endorsement codes.
  2. Request each endorsement with POST /v1/kyc/endorsements/{code}, such as usd_pr_bank_v1 for USD virtual accounts.
  3. If the response includes a new submission, complete that submission.
  4. Use either the KYC submission API flow or Due’s hosted flow.
  5. Confirm the endorsement is no longer blocking the channel.
  6. Create the virtual account.

Did this page help you?