GOWD BRL Corporate VA Opening

Use this flow when BPN has enabled an GOWD BRL primary account for your merchant. GOWD supports Corporate + STATIC opening through this API. Woovi individual profiles and other BRL channels' dynamic QR examples do not apply.

Before you start

Obtain your environment's API credentials and an GOWD BRL primaryAccountId from BPN. A BRL currency code alone does not select GOWD. The selected primary account determines the channel; a caller-supplied channelCode does not override it. Confirm that the target environment supports this flow before integration.

All paths below are relative to your BPN Base URL. See Environments and Authentication.

1. Upload the supporting documents

Upload one file for each required category:

CNPJ card: kycFormData.cartao_cnpj.

Articles of association: kycFormData.contrato_social.

UBO identity document: kycFormData.ubo_id_document.

For each file, call Request File Upload URL, POST /v1/files/upload-url:

{
  "documentType": "VA_ONBOARDING",
  "currency": "BRL",
  "fileType": "pdf",
  "fileSize": 284517
}

fileType is the file extension, not a MIME type. fileSize is the declared byte count; provide the actual size. The default policy accepts pdf/jpg/jpeg/png/heic, 10 KiB–10 MiB per file. Environment, currency or merchant policies can override these limits.

The response's data contains fileId, uploadUrl and expiresAt. Upload the raw file body to the complete URL before expiresAt:

Do not send BPN credentials or an Authorization header to the storage URL. Receiving a fileId only means the upload URL was issued; wait for the PUT to succeed before creating the account. If the URL expires, request a new URL and use its new fileId. Do not overwrite an uploaded document.

Use fileIds issued to the same merchant. Do not pass base64, storage keys, download URLs, fileListMap, companyInfo.companyFiles, or legacy file objects such as socialContract.

Multiple pages: the API accepts a single fileId, a comma-separated list, or an array, but only the first file for each GOWD document type is sent to GOWD. Merge all required pages or front/back images into one PDF within the file limits; do not rely on an array to transmit every page.

2. Create the account

Call Create Virtual Account, POST /v1/virtual-account/sub/create. Replace all sample IDs and company details. The PEP declaration must reflect the applicant's actual declaration.

{
  "primaryAccountId": "<GOWD_BRL_PRIMARY_ACCOUNT_ID>",
  "currency": "BRL",
  "accountSubType": "STATIC",
  "userType": "Corporate",
  "accountName": "Example Pagamentos LTDA",
  "cnpj": "<COMPANY_CNPJ>",
  "kycFormData": {
    "legal_name": "Example Pagamentos LTDA",
    "cartao_cnpj": "0f6c8a52-3c1e-4d7a-9b5e-2a1f7c9d4e01",
    "contrato_social": "5b2e9d14-7a3f-4c8b-a1d6-9e0f3b7c2a55",
    "ubo_full_name": "Example Beneficial Owner",
    "ubo_id_type": "passport",
    "ubo_id_document": "9c4d1e7a-2b6f-4a3e-8d5c-1f0e9a7b3c22",
    "pep_declaration_type": "PEP_NON_DECLARATION"
  }
}

Required values

primaryAccountId: use the GOWD BRL primary account confirmed by BPN. This guide requires an explicit account to avoid selecting another BRL channel through default routing.

currency=BRL, accountSubType=STATIC, userType=Corporate. CorporateSlave remains accepted for compatibility; use Corporate for new integrations. Individual, Business and DYNAMIC are not supported by this flow.

accountName or companyName: use the legal company name; keep them consistent if sending both.

cnpj: the actual company CNPJ. Do not supply it only as companyInfo.taxIdNumber. Formatting punctuation and whitespace are removed; there is no BPN length/check-digit restriction in this flow. Channel validation still applies.

kycFormData.legal_name: legal company name. Send it explicitly; companyName/accountName can supply the value if omitted.

kycFormData.ubo_full_name: UBO full name.

kycFormData.ubo_id_type: one of passport, national_id, rg, cin, rnm_rne, drivers_license, professional_registration, pr_card.

The three file fields and pep_declaration_type are required.

Keep the exact snake_case question IDs inside kycFormData. Do not convert them to camelCase. individualInfo, companyInfo.businessType and companyInfo.industry are not needed for GOWD. You may omit kycTemplateId; BPN resolves it when available. Do not supply server-managed userId or merchantId.

PEP conditional fields

PEP_NON_DECLARATION: no additional PEP fields.

IS_PEP: also supply pep_related_name and pep_public_role.

RELATED_TO_PEP: also supply pep_related_name, pep_public_role and pep_relationship.

For example, merge these values into kycFormData when applicable:

{
  "pep_declaration_type": "RELATED_TO_PEP",
  "pep_related_name": "<PEP_FULL_NAME>",
  "pep_public_role": "<PUBLIC_ROLE>",
  "pep_relationship": "<RELATIONSHIP>"
}

3. Track the result

Opening is asynchronous by default. Check the response envelope for business success and save data.virtualAccountId. A typical accepted data payload is:

{
  "virtualAccountId": "<RETURNED_VA_ID>",
  "currency": "BRL",
  "status": "PROCESSING"
}

HTTP 200 alone does not establish business success, and an accepted application is not a usable account. The initial status depends on processing progress; do not require an INIT response before accepting PROCESSING.

Call Get Virtual Account Detail:

GET /v1/virtual-account/sub/get?virtualAccountId=<RETURNED_VA_ID>

GET signature: query parameters must participate in the signature. For a single ID 12345, the HMAC message is virtualAccountId=12345&<timestampMillis>. It is not &<timestampMillis>. See Authentication for sorting and encoding rules.

INIT / PROCESSING: wait; do not present the account as ready to receive funds.

SUCCESS: read the actual pixKey, pixKeyType, accountNumber, bankName, bankBranchCode and bankIspb fields returned. QR code and QR image are not guaranteed for GOWD.

FAIL: inspect failReason and retain the virtualAccountId and traceId for support.

If subscribed to Open Virtual Account Status, verify webhook signatures, deduplicate by eventId, and query the detail API to confirm the result. Keep scheduled queries as a fallback, with backoff and the merchant's agreed rate limit. Do not assume a universal 48-hour completion guarantee.

4. Retries and errors

Missing field, document or conditional PEP detail: correct the application before resubmitting.

Missing/unuploaded file or file belonging to another merchant: complete the proper upload or request a new fileId.

Invalid primary account: ask BPN to confirm the account, channel and merchant access.

Same-name account still processing: query the existing application. Do not create parallel applications under different names to force a retry.

Same-name account already successful: reuse the existing account; duplicate creation is rejected.

Failed application: investigate and correct the reason before resubmitting. A same-name failed record can be reused; always use the ID returned by the latest response.

Network timeout or unknown submission result: reconcile the application before retrying. Do not assume a caller-supplied external ID provides universal idempotency.

File metadata query failure or prolonged PROCESSING: contact BPN with traceId and virtualAccountId.

Error codes and messages may be mapped by the environment. Inspect business status and data as well as HTTP status; do not depend on an exact message string.

GOWD BRL Corporate VA Opening

Before you start#

1. Upload the supporting documents#

2. Create the account#

Required values#

PEP conditional fields#

3. Track the result#