Skip to content

Logo

Sqala

Transforming payments with innovative technology

Supports in this guide: Payments, Payouts

Provider website: sqala.tech

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

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

Prerequisites: get from Sqala

Contact your Sqala account manager to get your account verified and receive the following credentials.

  • Application ID -> Corefy field app_id.
  • Password -> Corefy field password.
  • Refresh token -> Corefy field refresh_token -> used to obtain a Bearer access token for API calls.
  • Payment secret key -> Corefy field payment_secret_key -> optional, required only to verify Payments callback signatures.
  • Payout secret key -> Corefy field payout_secret_key -> optional, required only to verify Payouts callback signatures.

BRL only, via PIX.

Payments processing (connect Provider account, create payment-invoice)

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

Open Sqala in the provider directory and press Connect at Sqala Provider Overview page in the New connection section.

Step 2 - Fill in fields and select settings

  • Application ID
  • Password
  • Refresh token
  • Payment secret key -> optional, needed for Payments callback verification
  • Payout secret key -> optional, needed for Payouts callback verification

Success

You have connected Sqala Provider account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice via the pix_qr_brl_invoice service - the customer pays by scanning a PIX QR code.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "f21ffeff-20dd-44be-a99d-c86ffe0d1527",
      "service": "pix_qr_brl_invoice",
      "currency": "BRL",
      "amount": 1.98
    }
  }
}

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "a3f6e2c1-8d4b-4a9e-9f0c-1b2d3e4f5a6b",
      "service": "pix_qr_brl_invoice",
      "currency": "BRL",
      "amount": 1.98,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Doe",
        "individual_tax_id": "01234567890"
      },
      "fields": {
        "payer_first_name": "John",
        "payer_last_name": "Doe",
        "cpf_number": "01234567890"
      }
    }
  }
}

Important

  • If the connection's customer_cpf_validation option is enabled, a payer name and CPF (Brazilian tax ID) are sent to Sqala: fields.payer_first_name/fields.payer_last_name take priority, falling back to customer.name; fields.cpf_number takes priority, falling back to customer.individual_tax_id.
  • A second Payments service, pix_brl_hpp, is also available - a PIX redirect/HPP flow instead of a QR code (see Options below for its required provider_action_url).
  • No customer fields are faked when missing - they are simply omitted from the request.

Extended request (MAX)

Why add extra fields (typical reasons): - Provide additional customer details for compliance/reconciliation - Positively influence conversion rate - Include optional fields required by your specific flow

Options

  • customer_cpf_validation -> required, boolean, for the pix_qr_brl_invoice service - when enabled, sends the payer's name and CPF to Sqala (see above).
  • provider_action_url -> required, string, for the pix_brl_hpp service - your own return/checkout URL that the customer is redirected to after paying.
  • custom_finalize_payment -> optional, boolean, for the pix_brl_hpp service.

Constants (fallback fields)

Constants are static values that Corefy can send to the provider instead of dynamic data from your API request, when those fields are missing in the request.

Priority (predictable rule): 1. If a value is present in the request -> Corefy uses the request value 2. Else if the constant is set -> Corefy uses the constant 3. Else -> provider may reject the request or apply its defaults (depends on provider)

Currently available constants (constant -> Corefy API field)

  • CHECKOUT_LOGO_URL -> sent only for the pix_brl_hpp service, as the checkout page logo

Refunds

Sqala does not support refunds.

Payouts processing (connect Provider account, create payout-invoice)

Connect Provider account in Corefy Dashboard

Uses the same Provider account connected above - no separate connection step.

First request to Corefy API (MIN)

What it does: creates a payout-invoice and sends funds via PIX.

Payout - MIN

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "f23ab13a-383b-4fd5-a973-41163ae14233",
      "service": "pix_brl",
      "currency": "BRL",
      "amount": 1,
      "fields": {
        "pix_key": "987987327978"
      }
    }
  }
}

Important

fields.pix_key is required - the payout is rejected before it's sent to Sqala if it's missing.

Payout - MAX

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
      "service": "pix_brl",
      "currency": "BRL",
      "amount": 1,
      "customer": {
        "reference_id": "cus_456"
      },
      "fields": {
        "pix_key": "987987327978"
      }
    }
  }
}

Extended request (MAX)

Why add extra fields (typical reasons): - Provide additional customer details for compliance/reconciliation - Include optional fields required by your specific flow

Additional info

  1. Active reconciliation is available on both Payments and Payouts - Corefy can actively request a status in addition to the asynchronous callback.
  2. Callback signatures are verified only if the matching secret key is set - without payment_secret_key/payout_secret_key, Sqala's callbacks for that flow are rejected as unverifiable.
  3. No recurring - this connector does not support saving/charging a token through Corefy.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify the Application ID, Password, and Refresh token
  • Callback rejected as invalid signature -> make sure the matching payment_secret_key/payout_secret_key is set on the connection
  • Payout rejected for missing fields -> fields.pix_key is required for every payout
  • Currency or service is not supported -> only BRL via PIX is available
  • Refund fails -> Sqala does not support refunds through Corefy

Question

Still looking for help connecting your Sqala account? Please contact our support team!