AstroPay

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

• API Key
• Secret Key
• Test Mode -> (enable if you are using sandbox credentials)

First request to Corefy API (MIN)

What it does: creates a payment-invoice for a Pix QR code payment (service pix_qr_brl_invoice, BRL only). Corefy returns a QR code for the customer to scan in their banking app.

Payment - MIN

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "7ede4873-f088-4337-8075-685c103a80d9",
      "service": "pix_qr_brl_invoice",
      "currency": "BRL",
      "amount": 100,
      "service_fields": {
        "cpf_number": "12345678909"
      }
    }
  }
}

Payment - MAX

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "37d82640-6b4b-4175-b051-f13b5b76c8cb",
      "service": "pix_qr_brl_invoice",
      "currency": "BRL",
      "amount": 100,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Doe",
        "email": "johndoe@example.com",
        "phone": "+551234456789",
        "date_of_birth": "2000-05-25",
        "address": {
          "country": "BR"
        }
      },
      "service_fields": {
        "cpf_number": "12345678909"
      }
    }
  }
}

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

• finalize_by_protocol -> optional, boolean - AstroPay does not always guarantee that a fail status is final (it can later change to success). Enable this option to let Corefy stop failing payments on AstroPay's unreliable decline signal, at the cost of possible status discrepancies for the merchant.
• ignore_provider_amount -> optional, boolean - AstroPay can report the deposit/payout in a different currency/amount than the one your merchant account was configured with (for example you send 10 BRL but AstroPay's response is in the account's own currency, e.g. USD). Enable this option to skip amount/currency validation against AstroPay's response and finalize automatically; leave it disabled to finalize such mismatched transactions manually. This option also applies to Payouts (see below).

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)

• REFERENCE_ID -> customer.reference_id
• COUNTRY -> customer.address.country
• FIRST_NAME -> customer.name (first part)
• LAST_NAME -> customer.name (second part)
• EMAIL -> customer.email
• PHONE -> customer.phone
• DATE_OF_BIRTH -> customer.date_of_birth
• MCC -> falls back from your Corefy merchant profile's MCC when neither is set, no request field
• MERCHANT_CODE -> no request field, constant only
• CATEGORY -> no request field, constant only
• DESCRIPTION -> no request field, constant only

Refunds

AstroPay does not support refunds through this connector.

Connect Provider account in Corefy Dashboard

Payouts use the same Provider account and credentials as Payments - no separate connection needed.

First request to Corefy API (MIN)

What it does: creates a payout-invoice and sends funds via Pix (service pix_brl, BRL only) directly to a recipient identified by their Brazilian tax ID (CPF), phone number, or email, depending on your configured Pix key type.

Payout - MIN

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "3c4d5e6f-7a8b-4c9d-8e02-3f4a5b6c7d8e",
      "service": "pix_brl",
      "currency": "BRL",
      "amount": 100,
      "fields": {
        "cpf_number": "12345678909"
      }
    }
  }
}

Payout - MAX

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "4d5e6f7a-8b9c-4d0e-8f13-4a5b6c7d8e9f",
      "service": "pix_brl",
      "currency": "BRL",
      "amount": 100,
      "customer": {
        "reference_id": "cus_123",
        "address": {
          "country": "BR"
        }
      },
      "fields": {
        "cpf_number": "12345678909",
        "beneficiary_name": "John",
        "beneficiary_lastname": "Doe",
        "beneficiary_phone": "+551234456789",
        "beneficiary_email": "johndoe@example.com"
      }
    }
  }
}

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

• ignore_provider_amount -> optional, boolean - same mechanism as on Payments: skip amount/currency validation against AstroPay's response and finalize payouts automatically, instead of finalizing mismatched ones manually.

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)

• REFERENCE_ID -> customer.reference_id
• COUNTRY -> customer.address.country
• FIRST_NAME -> fallback for fields.beneficiary_name
• LAST_NAME -> fallback for fields.beneficiary_lastname
• EMAIL -> fallback for fields.beneficiary_email
• PHONE -> fallback for fields.beneficiary_phone

AstroPay does not support refunds for payouts.