Usage Examples

This page provides practical examples of how to interact with the CorpX API using cURL, in the logical order of a typical integration.

Environment Variables

Configure these variables before running the examples:

# OAuth Credentials (provided during onboarding)
export CLIENT_ID="your_client_id"
export CLIENT_SECRET="your_client_secret"

# Account identifiers
export TENANT_ID="your-tenant-uuid"
export ACCOUNT_ID="your-account-uuid"

# Environment URLs
export API_URL="https://api.corpxapi.com"
export AUTH_URL="https://auth.corpxapi.com"

1. Authentication

The first step is to obtain an OAuth2 access token using your client credentials.

curl -X POST "${AUTH_URL}/oauth2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=${CLIENT_ID}" \
     -d "client_secret=${CLIENT_SECRET}"

Successful response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Store the token for use in subsequent calls:

export JWT="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

2. Check Balance

Check the available and locked balance of your account in real time.

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/balance" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

Response:

{
  "accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
  "total": 15000.00,
  "locked": 500.00,
  "available": 14500.00,
  "currency": "BRL",
  "updatedAt": "2024-01-15T10:30:00Z",
  "locks": [
    {
      "lockId": "lock-abc123",
      "amount": 500.00,
      "currency": "BRL",
      "reason": "MED investigation",
      "medId": "med-12345",
      "status": "active",
      "createdAt": "2024-01-10T14:00:00Z"
    }
  ]
}

3. Generate Dynamic QR Code (Receiving)

Generate a dynamic QR Code to receive a PIX payment for a specific amount.

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/qr-code/dynamic" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "pixKey": "contact@mycompany.com",
       "value": 150.00,
       "expirationDate": "2024-12-31T23:59:59Z",
       "allowChangeValue": false,
       "message": "Payment for order #12345",
       "identifier": "order-12345",
     }'

Value	Description
`IMAGE`	Returns a Base64 image of the QR Code
`EMV`	Returns only the copy-and-paste string

4. Generate Static QR Code

Static QR Codes do not expire and are ideal for permanent display.

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/qr-code/static" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "pixKey": "contact@mycompany.com",
       "value": 50.00,
       "message": "Donation to project XYZ",
       "identifier": "doacao-xyz-001",
     }'

5. Check QR Code Status

Check whether the previously generated QR Code has been paid or is still pending.

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/qr-code?identifier=order-12345" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

6. PIX Out (Transfer via Key)

Send a PIX to a third-party key (outbound transfer).

Need to send PIX without a PIX key? If you only have the recipient's bank details (ISPB, branch and account number), use the dedicated endpoint POST /v1/accounts/{accountId}/pix/out/bank-account. See the v1.27.0 changelog for details.

6.1 PIX to CPF

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 150.00,
       "currency": "BRL",
       "keyType": "CPF",
       "key": "12345678900",
       "description": "Service payment",
       "identifier": "order-456"
     }'

6.2 PIX to Email

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 75.50,
       "currency": "BRL",
       "keyType": "EMAIL",
       "key": "supplier@company.com",
       "description": "Pagamento NF 789"
     }'

6.3 PIX to Phone

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 200.00,
       "currency": "BRL",
       "keyType": "PHONE",
       "key": "+5511999999999",
       "description": "Transfer"
     }'

6.4 PIX to Random Key (EVP)

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "amount": 500.00,
       "currency": "BRL",
       "keyType": "EVP",
       "key": "123e4567-e89b-12d3-a456-426614174000",
       "description": "Pagamento de fornecedor"
     }'

Values for keyType:

Value	Description	Format
`CPF`	Recipient's CPF	11 digits (numbers only)
`CNPJ`	Recipient's CNPJ	14 digits (numbers only)
`EMAIL`	Recipient's email	Valid email
`PHONE`	Recipient's phone	+55 + area code + number
`EVP`	Random key	UUID v4

Successful response:

{
  "transactionId": "txn-abc123-def456",
  "status": "APPROVED",
  "endToEndId": "E12345678202401151234abcdefghijkl",
  "amount": 150.00,
  "currency": "BRL"
}

Values for status:

Value	Description
`APPROVED`	Transfer approved and completed
`PENDING`	Awaiting bank confirmation
`PROCESSING`	In processing
`REJECTED`	Rejected (check the error message)

6.5 Check Transfer Status

Check the status of a transfer using the E2E ID:

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/transactions?endToEndId=E12345678202401151234abcdefghijkl" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

Response:

{
  "transactionId": "txn-abc123-def456",
  "endToEndId": "E12345678202401151234abcdefghijkl",
  "status": "COMPLETED",
  "type": "CASH_OUT",
  "amount": -150.00,
  "currency": "BRL",
  "description": "PIX - MARIA DA SILVA",
  "transactionDate": "2024-01-15T12:34:00Z",
  "counterparty": {
    "name": "MARIA DA SILVA",
    "document": "123***01",
    "bankCode": "001"
  },
  "balance": 14350.00
}

Query parameters:

Parameter	Description
`accountId`	Account ID (required)
`endToEndId`	Transaction E2E ID
`identifier`	Charge or reference identifier

Note: At least one of the parameters endToEndId or identifier is required.

7. Pay QR Code (PIX Out via EMV)

Pay a PIX QR Code using the EMV string (copy and paste).

7.1 Pay Dynamic QR Code (pre-defined amount)

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out/qr-code" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000520400005303986540510.005802BR5913Loja Exemplo6008Sao Paulo62070503***6304ABCD",
       "description": "Pagamento de compra online"
     }'

7.2 Pay Static QR Code (specifying amount)

For static QR Codes without a defined amount, the amount field is required:

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out/qr-code" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "emv": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000520400005303986540010.005802BR5913Loja Exemplo6008Sao Paulo62070503***6304EFGH",
       "amount": 150.00,
       "description": "Service payment"
     }'

Successful response:

{
  "transactionId": "txn-qr-abc123",
  "status": "APPROVED",
  "endToEndId": "E12345678202401151234mnopqrstuvwx",
  "amount": 150.00,
  "currency": "BRL"
}

8. Request Refund

Refund a previously received PIX (fully or partially).

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/out/refund" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "accountId": "'${ACCOUNT_ID}'",
       "originalEndToEnd": "E12345678202401101234abcdefghijkl",
       "amount": 150.00,
       "currency": "BRL",
       "reason": "Product not available in stock"
     }'

Response:

{
  "refundId": "ref-abc123-def456",
  "status": "PROCESSING",
  "amount": 150.00,
  "currency": "BRL"
}

Values for refund status:

Value	Description
`PROCESSING`	Refund in processing
`COMPLETED`	Refund completed successfully
`REJECTED`	Refund rejected

9. List Recent Transactions (Statement)

Retrieve the recent transaction history of the account.

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/statement?limit=10&order=desc" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

Query parameters:

Parameter	Type	Description
`page`	integer	Page index (0-based)
`size`	integer	Page size (max 500)
`startDate`	datetime	Start date filter (ISO 8601)
`endDate`	datetime	End date filter (ISO 8601)
`limit`	integer	Total record limit (max 1000)
`order`	string	Sort order: `asc` or `desc`

10. Manage PIX Keys

10.1 List PIX Keys

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

10.2 Register a New PIX Key

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "keyType": "email",
       "pixKey": "financeiro@minhaempresa.com.br"
     }'

Values for keyType on registration:

Value	Description
`cpf`	CPF of the account holder
`cnpj`	CNPJ of the account holder
`phone`	Phone number (+5511999999999)
`email`	Email address
`random`	Random key (EVP) - automatically generated by the system

10.3 Register a Random Key (EVP)

For random keys, omit the pixKey field:

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "keyType": "random"
     }'

10.4 Delete a PIX Key

curl -X DELETE "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/keys/contact%40mycompany.com" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

11. Query MEDs (Special Return Mechanism)

Query infractions and disputes opened via MED.

curl -X GET "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/med?status=OPEN&limit=20" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}"

Filter parameters:

Parameter	Values	Description
`status`	`OPEN`, `IN_PROGRESS`, `CLOSED`, `CANCELED`	MED status
`responseStatus`	`PENDING`, `AGREED`, `DISAGREED`	Response status
`minAmount`	number	Minimum amount
`maxAmount`	number	Maximum amount
`from`	datetime	Start date
`to`	datetime	End date
`limit`	integer	Result limit
`cursor`	string	Pagination cursor

11.1 Respond to a MED

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/pix/med/med-12345/response" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Content-Type: application/json" \
     -d '{
       "answer": "DISCORDO",
       "message": "Legitimate transaction as per attached receipts",
       "evidences": [
         {
           "order": 1,
           "description": "Comprovante de entrega",
           "url": "https://storage.exemplo.com/evidencia1.pdf"
         }
       ]
     }'

Values for answer:

Value	Description
`CONCORDO`	Accepts the requested refund
`DISCORDO`	Disputes the refund request

12. Internal Transfer

Transfer funds between accounts in the same bank (no cost, instant).

curl -X POST "${API_URL}/v1/accounts/${ACCOUNT_ID}/transfers/internal" \
     -H "Authorization: Bearer ${JWT}" \
     -H "X-Tenant-Id: ${TENANT_ID}" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "branch": "0001",
       "account": "123456-7",
       "taxNumber": "12345678900",
       "value": 500.00,
       "message": "Transfer between accounts",
       "identifier": "transf-int-12345"
     }'

Common Error Handling

Insufficient Balance

{
  "errorCode": "insufficient_balance",
  "message": "insufficient available balance: 50.00 (total: 100.00, locked: 50.00, requested: 150.00)"
}

Invalid PIX Key

{
  "errorCode": "invalid_payload",
  "message": "keyType must be one of: CPF, CNPJ, EMAIL, PHONE, EVP"
}

Idempotency Conflict

{
  "errorCode": "idempotency_conflict",
  "message": "Request with same Idempotency-Key but different payload"
}

Best Practices

Always use Idempotency-Key on POST/PUT/PATCH operations to avoid duplicates
Store the endToEndId of transactions for tracking and refunds
Implement retry with exponential backoff for 5xx errors
Validate the balance before outbound operations for better UX
Configure webhooks to receive real-time notifications

For more details about each endpoint, see the API Reference or the Integration Guide.

Environment Variables​

1. Authentication​

2. Check Balance​

3. Generate Dynamic QR Code (Receiving)​

4. Generate Static QR Code​

5. Check QR Code Status​

6. PIX Out (Transfer via Key)​

6.1 PIX to CPF​

6.2 PIX to Email​

6.3 PIX to Phone​

6.4 PIX to Random Key (EVP)​

6.5 Check Transfer Status​

7. Pay QR Code (PIX Out via EMV)​

7.1 Pay Dynamic QR Code (pre-defined amount)​

7.2 Pay Static QR Code (specifying amount)​

8. Request Refund​

9. List Recent Transactions (Statement)​

10. Manage PIX Keys​

10.1 List PIX Keys​

10.2 Register a New PIX Key​

10.3 Register a Random Key (EVP)​

10.4 Delete a PIX Key​

11. Query MEDs (Special Return Mechanism)​

11.1 Respond to a MED​

12. Internal Transfer​

Common Error Handling​

Insufficient Balance​

Invalid PIX Key​

Idempotency Conflict​

Best Practices​

Environment Variables

1. Authentication

2. Check Balance

3. Generate Dynamic QR Code (Receiving)

4. Generate Static QR Code

5. Check QR Code Status

6. PIX Out (Transfer via Key)

6.1 PIX to CPF

6.2 PIX to Email

6.3 PIX to Phone

6.4 PIX to Random Key (EVP)

6.5 Check Transfer Status

7. Pay QR Code (PIX Out via EMV)

7.1 Pay Dynamic QR Code (pre-defined amount)

7.2 Pay Static QR Code (specifying amount)

8. Request Refund

9. List Recent Transactions (Statement)

10. Manage PIX Keys

10.1 List PIX Keys

10.2 Register a New PIX Key

10.3 Register a Random Key (EVP)

10.4 Delete a PIX Key

11. Query MEDs (Special Return Mechanism)

11.1 Respond to a MED

12. Internal Transfer

Common Error Handling

Insufficient Balance

Invalid PIX Key

Idempotency Conflict

Best Practices