Stark Bank

Supports in this guide: Payments, Payouts

Provider website: starkbank.com

What you need to do for start processing transactions (brief summary)

1. Get your credentials (from Stark Bank)
2. Connect in Dashboard
3. Send an API request

Choose account type

Corefy offers two account types for Stark Bank: an H2H Merchant account for Payments (PIX), and a Provider account for Payouts (PIX transfers). Both use the same Project ID/Private key pair, but connecting one does not automatically connect the other - connect each separately depending on which flows you need.

Prerequisites: get from Stark Bank

Contact your Stark Bank account manager to get your project set up and receive the following credentials.

• Project ID -> Corefy field project_id.
• Private key -> Corefy field private_key -> uploaded as a file; used to sign every API request sent to Stark Bank.

BRL only.

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "683e34ef-f981-42ec-a7de-06c7d03142dd",
      "service": "pix_brl_hpp",
      "currency": "BRL",
      "amount": 5,
      "service_fields": {
        "cpf_number": "012.345.678-90"
      }
    }
  }
}

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "ab2f6d9e-1234-4a2b-9c3d-0e1f2a3b4c5d",
      "service": "pix_qr_brl_invoice",
      "currency": "BRL",
      "amount": 5,
      "service_fields": {
        "cpf_number": "012.345.678-90",
        "payer_first_name": "Test",
        "payer_last_name": "Test"
      }
    }
  }
}

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "ab765f27-840e-41b9-9c1c-2b5238a8cd19",
      "service": "pix_brl",
      "currency": "BRL",
      "amount": 1,
      "fields": {
        "cpf_number": "11968409700",
        "beneficiary_name": "Joao",
        "beneficiary_lastname": "Francisco",
        "bank_isbp_code": "18236120",
        "bank_branch_code": "0001",
        "account_number": "41818451-6"
      }
    }
  }
}

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "3f4e5d6c-7b8a-4910-9c2d-1e3f5a7b9c0d",
      "service": "pix_brl",
      "currency": "BRL",
      "amount": 1,
      "fields": {
        "pix_key": "11968409700"
      }
    }
  }
}

Additional info

1. Active reconciliation and callbacks are both available on Payments and Payouts - Corefy can poll Stark Bank for the current status, and Stark Bank also pushes webhook notifications; callback signatures are verified using the public key Corefy fetched automatically during connection.
2. Corefy's own outbound IPs are fixed - if your Stark Bank project enforces an IP allow-list, add 35.199.76.124, 34.85.188.162, 35.247.226.240, and 35.245.182.229.
3. No recurring - this connector does not support saving/charging a token through Corefy.
4. No hardcoded placeholder fallbacks - if the payer's CPF or name is missing from the request, it is sent to Stark Bank as empty/absent rather than a fake substituted value.

FAQ / Troubleshooting

• Invalid credentials / auth error -> verify the Project ID and the uploaded private key belong to the same Stark Bank project, and that test_mode matches your credentials' environment
• Connection test fails -> Corefy needs to successfully fetch your public key and register its webhook during connection - make sure your project is active and not blocking Corefy's IPs
• Payment is rejected for a different payer's CPF -> customer_cpf_validation is enabled by default and restricts payment to the exact CPF submitted; disable it if you want to accept payment from any CPF
• Payout rejected for missing bank details -> either send the direct bank fields (cpf_number, bank_isbp_code, bank_branch_code, account_number) or enable use_dict_key and send fields.pix_key instead
• Currency or service is not supported -> only BRL is available, via pix_brl_hpp/pix_qr_brl_invoice (Payments) and pix_brl (Payouts)
• Refund fails with multiple attempts -> only one refund per payment is allowed