OKTO

Supports in this guide: Payments, Payouts

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

Get your credentials (from OKTO)
Connect in Dashboard
Send an API request

Prerequisites: get from OKTO

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

Merchant account number -> Corefy field merchant_account_number.
API key -> Corefy field api_key.
Callback signature key -> Corefy field callback_signature_key.
Country -> Corefy field country - the account is created for a single country; choose one of: Mexico, Argentina, Peru, Chile, Brazil.

Important

OKTO is a single Provider account per country. Brazil uses a dedicated Pix flow that behaves differently from the other four countries (see the notes below) - if you need to process several countries, connect a separate Provider account for each.

Card, bank transfer, cash (country-dependent), and Pix (Brazil only).

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

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

Merchant account number
API key
Callback signature key
Country -> Mexico, Argentina, Peru, Chile, or Brazil
Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected OKTO Provider account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice and redirects the customer to OKTO's hosted checkout for the selected local payment method. Available services depend on the account's country:

Country	Currency	Example services
Mexico	MXN	`payment_card_mxn_hpp`, `bank_transfer_mxn_hpp`, `cash_mxn_hpp`
Argentina	ARS	`bank_transfer_ars_hpp`
Peru	PEN	`bank_transfer_pen_hpp`, `cash_pen_hpp`
Chile	CLP	`payment_card_clp_hpp`, `bank_transfer_clp_hpp`
Brazil	BRL	`pix_brl_hpp`

Important

Confirm the exact service list enabled for your account and country in Corefy - not every method shown above is necessarily available on every account.

Payment - MIN (Mexico, bank transfer)

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "13dec2f4-4660-409a-8ddc-bdb5e10de1a2",
      "service": "bank_transfer_mxn_hpp",
      "currency": "MXN",
      "amount": 57,
      "customer": {
        "reference_id": "33cbc7ab-8ad2-4235-8b26-9d9dd9dee5e9",
        "name": "John Doe",
        "email": "test@example.com"
      },
      "service_fields": {
        "document_type": "TAX_ID_NUMBER",
        "document_id": "152612XXXX6765"
      }
    }
  }
}

Important

customer.reference_id, customer.name (split into first/last), and customer.email are all required for Mexico, Argentina, Peru, and Chile.
service_fields.document_type/.document_id are required by most local methods in these four countries for identity verification - the exact required service_fields set depends on the selected service; check with your OKTO account manager.

Payment - MIN (Brazil, Pix)

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "d1dc6082-dca7-4cce-b06a-6331951c5b15",
      "service": "pix_brl_hpp",
      "currency": "BRL",
      "amount": 75,
      "customer": {
        "reference_id": "20af9b35-fbd7-410e-9736-adeea7f22176",
        "name": "John Doe"
      },
      "service_fields": {
        "cpf_number": "604.184.437-34"
      }
    }
  }
}

Important

For Brazil (Pix), only customer.name is used by OKTO - customer.email is not sent. service_fields.cpf_number is required.

Payment - MAX

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "fcaf86bf-1998-4356-aa94-b8f2e3f8274f",
      "service": "bank_transfer_pen_hpp",
      "currency": "PEN",
      "amount": 53,
      "customer": {
        "reference_id": "abe2ad63-30df-4e9c-9a05-06e23c5a5beb",
        "name": "John Doe",
        "email": "test@example.com"
      },
      "service_fields": {
        "document_type": "TAX_ID_NUMBER",
        "document_id": "27983285123"
      }
    }
  }
}

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

Refunds

OKTO supports refunds in both Brazil (Pix) and the other four countries, but only a single full refund per payment (no partial, no multiple refunds against the same payment).

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.

Important

Payouts are not available for Brazil (Pix) - the account's country must be Mexico, Argentina, Peru, or Chile.

First request to Corefy API (MIN)

What it does: creates a payout-invoice and sends funds via bank transfer to the customer.

Payout - MIN

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "a1b2c3d4-5e6f-4789-8a02-5b6c7d8e9f0a",
      "service": "bank_transfer_mxn",
      "currency": "MXN",
      "amount": 57,
      "customer": {
        "reference_id": "33cbc7ab-8ad2-4235-8b26-9d9dd9dee5e9"
      }
    }
  }
}

Payout - MAX

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "b2c3d4e5-6f70-4891-9b03-6c7d8e9f0a1b",
      "service": "bank_transfer_mxn",
      "currency": "MXN",
      "amount": 57,
      "customer": {
        "reference_id": "33cbc7ab-8ad2-4235-8b26-9d9dd9dee5e9",
        "name": "John Doe",
        "email": "test@example.com"
      }
    }
  }
}

Important

customer.name and customer.email are optional on Payouts but recommended - OKTO accepts the payout without them.

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

Additional info

Active reconciliation is available on both flows - Payments and Payouts each have both an asynchronous callback and an active status request.
No recurring - this connector does not support saving/charging a token through Corefy.
No Options or Constants are configured for this connector.

FAQ / Troubleshooting

Invalid credentials / auth error -> verify the merchant account number, API key, and that the account's country matches your OKTO account
Callback signature mismatch -> verify the callback signature key configured in Corefy matches the one issued by OKTO
Payout rejected -> confirm the account's country is Mexico, Argentina, Peru, or Chile - Brazil (Pix) accounts do not support Payouts
Currency or service is not supported -> confirm allowed currencies/services for your account's country in your OKTO account and in Corefy
Refund fails with multiple attempts -> only one full refund per payment is allowed

Question

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