Paycos

Paycos provides contemporary software and technical solutions from top ranked specialists.

Supports in this guide: Payments | Payouts

Provider website: paycos.com

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

Choose account type
Get your credentials (from Paycos)
Connect in Dashboard
Send an API request

Choose account type

Paycos can be connected in different ways (depending on your needs):

If you do H2H card payments (card data sent directly) -> choose H2H Merchant account
If you do payments via local payment methods (customer redirected to a bank/e-wallet page) -> choose Provider account
If you do payouts -> choose Provider account

The same Provider account connection covers both local payment methods and payouts - you don't need to connect it twice. If you're not sure which one to use, confirm with your Corefy account manager.

Prerequisites: get from Paycos

Get the following values for your Paycos project/account.

For H2H Merchant account (card payments):

Merchant ID -> Corefy field merchant_id -> where to find: Paycos backoffice / issued by Paycos manager
Private Key -> Corefy field private_key -> used as the Bearer token on every request to Paycos and to verify callback signatures -> where to find: Paycos backoffice / issued by Paycos manager
API URL -> Corefy field api_url -> your dedicated payment endpoint; Paycos issues an individual API host per merchant -> where to find: Paycos backoffice / issued by Paycos manager
API Status URL -> Corefy field api_status_url -> your dedicated endpoint for payment status checks, issued the same way -> where to find: Paycos backoffice / issued by Paycos manager

For Provider account (local payment methods & payouts):

Merchant Private Key -> Corefy field merchant_private_key -> used as the Bearer token on every request to Paycos and to verify callback signatures -> where to find: Paycos backoffice / issued by Paycos manager
Currency -> Corefy field currency -> the single settlement currency for this connection; choose one of the currencies supported by the local payment methods or payout methods you plan to use (BRL, UAH, TRY, AZN, UZS, EUR)

Payments processing (connect H2H Merchant account, create payment-invoice)

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

Open Paycos in the provider directory and press Connect at Paycos Provider Overview page in the New connection section. Choose H2H Merchant account.

Step 2 - Fill in fields and select settings

Merchant ID
Private Key
API URL
API Status URL
Currency / Features -> choose values available for your account (RUB, EUR, USD)

Success

You have connected Paycos H2H Merchant account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice. Card data itself is collected and submitted separately by Corefy's own checkout/card vault layer, not as a field inside this request.

Payment - MIN

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "6be05631-8710-4b14-a369-1928a2b70eda",
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 100
    }
  }
}

Payment - MAX

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "199be985-c243-478a-86a8-4b8c902e5bb6",
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 100,
      "customer": {
        "reference_id": "bc75bc54-5023-4f98-8c0d-ec5ed7e8f380",
        "email": "johnsmith@gmail.com",
        "phone": "+15551234567",
        "name": "John Smith",
        "date_of_birth": "1990-05-14",
        "address": {
          "country": "DE",
          "city": "Berlin",
          "full_address": "1st Street 1"
        }
      }
    }
  }
}

Every field inside customer above is optional - Paycos reads email, phone, name (split into first/last name), date_of_birth, and address.country/address.city/address.full_address, falling back to your account's Constants (see below) when a field is missing from the request, and omitting it entirely if neither is set.

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

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 -> the field is omitted from the request entirely

Currently available constants (constant -> Corefy API field)

FIRST_NAME -> customer.name
LAST_NAME -> customer.name
EMAIL -> customer.email
PHONE -> customer.phone
DATE_OF_BIRTH -> customer.date_of_birth
COUNTRY -> customer.address.country
CITY -> customer.address.city
FULL_ADDRESS -> customer.address.full_address

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

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

Merchant Private Key
Currency -> choose the settlement currency for this connection

Success

You have connected Paycos Provider account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice.

Payment - MIN

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "6be05631-8710-4b14-a369-1928a2b70eda",
      "service": "pix_brl_hpp",
      "currency": "BRL",
      "amount": 100,
      "fields": {
        "cpf_number": "12345678909"
      }
    }
  }
}

fields.cpf_number (the payer's Brazilian tax ID) is required for PIX, PicPay, Boleto Bancario, and Bank Transfer (BRL). Amounts must be whole currency units - Paycos rejects any amount with a fractional/cents part (e.g. 100, not 100.50).

Payment - MAX

POST /api/payment-invoices

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "199be985-c243-478a-86a8-4b8c902e5bb6",
      "service": "pix_brl_hpp",
      "currency": "BRL",
      "amount": 100,
      "customer": {
        "reference_id": "bc75bc54-5023-4f98-8c0d-ec5ed7e8f380",
        "name": "John Smith"
      },
      "fields": {
        "cpf_number": "12345678909"
      }
    }
  }
}

customer.name is split into the payer's first/last name. customer.reference_id and customer.name are both optional, falling back to this connection's Constants (see below).

Important

Boleto Bancario (boleto_bancario_brl_hpp) additionally requires a complete customer profile: customer.name, customer.email, and a full customer.address (country, street, full_address, city, region, post_code). The payment is rejected if any of these are missing - Constants do not cover this requirement.

Paycos also offers a large family of local redirect/invoice payment methods that need no fields at all - the customer is simply redirected to complete the payment on the selected bank/method's own page:

Currency	Local methods (`service` code)
UAH	`monobank_uah_invoice`, `otpbank_uah_invoice`, `pumb_uah_invoice`, `sensebank_uah_invoice`, `privatbank_uah_invoice`, `card_transfer_aggregated_uah_invoice`
TRY	`ziraat_bank_try_invoice`, `garanti_bbva_try_invoice`, `turkiye_finans_bank_try_invoice`, `papara_try_invoice`
AZN	`leobank_azn_invoice`, `rabitabank_azn_invoice`, `kapital_bank_azn_invoice`, `international_bank_of_azerbaijan_azn_invoice`, `unibank_azn_invoice`, `azer_turk_bank_azn_invoice`, `m10_azn_invoice`
UZS	`card_transfer_uzcard_uzs_invoice`, `card_transfer_humo_uzs_invoice`
BRL	`pix_qr_brl_invoice` (requires `fields.cpf_number`, same as `pix_brl_hpp` above)

Check with your Corefy account manager which of these are enabled for your account.

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

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. They are configured per service code.

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 -> the field is omitted from the request entirely

Currently available constants (constant -> Corefy API field)

CUSTOMER_REFERENCE_ID -> customer.reference_id
CUSTOMER_EMAIL -> customer.email
CUSTOMER_ADDRESS -> customer.address.full_address
CHECKOUT_LANGUAGE -> checkout page locale (2-letter code)

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

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields (provider -> Corefy)

Merchant Private Key -> merchant_private_key
Currency -> currency

Success

You have connected Paycos Provider account!

First request to Corefy API (MIN)

What it does: creates a payout-invoice.

Payout - MIN

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "86e68af6-6b95-4cc0-be16-e4df8044604c",
      "service": "pix_brl",
      "currency": "BRL",
      "amount": 100,
      "fields": {
        "cpf_number": "12345678909",
        "pix_key": "12345678909"
      }
    }
  }
}

fields.cpf_number and fields.pix_key are both required for PIX payouts. Amounts must be whole currency units - Paycos rejects any amount with a fractional/cents part.

Payout - MAX

POST /api/payout-invoices

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "08f5e97c-1170-4bda-9625-3bde3c6dcd20",
      "service": "pix_brl",
      "currency": "BRL",
      "amount": 100,
      "customer": {
        "reference_id": "55041b5b-adfd-4073-a92b-fd8b495a4cc1"
      },
      "fields": {
        "cpf_number": "12345678909",
        "pix_key": "12345678909"
      }
    }
  }
}

Paycos also supports:

Bank Transfer payouts (bank_transfer_brl, bank_transfer_try) - requires fields.cpf_cnpj_number, fields.bank_account_digit, fields.bank_code, fields.bank_branch, and fields.account_number.
Card payouts (payment_card_uzs, payment_card_azn, payment_card_uah, payment_card_eur) - the card number, expiry, and holder name come from Corefy's own card data source, the same way as any other card payout; no extra fields are required.

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

H2H Merchant account:

Paycos issues a dedicated API URL and API Status URL per merchant rather than a single shared endpoint - get both from your Paycos account manager before connecting.
Refunds are not currently supported through Corefy's Paycos connector for card payments.

Provider account (local payment methods & payouts):

Amounts must be whole currency units for both local-method payments and payouts - any amount with a fractional/cents part is rejected.
Boleto Bancario payments require a complete customer name, email, and billing address - see the !!! important note above.
Refunds are not currently supported through Corefy's Paycos connector for local payment methods.

FAQ / Troubleshooting

Invalid credentials / auth error -> verify your Merchant ID/Private Key (H2H Merchant account) or Merchant Private Key (Provider account) match the selected account type
"The value of the amount should be without pennies" -> Paycos (Provider account) requires whole-currency-unit amounts; round the amount before sending
Boleto payment rejected -> make sure customer.name, customer.email, and a full customer.address are all provided - Boleto has no fallback Constants
Missing customer data on H2H card payments -> set Constants (see above) or provide the fields in your API request
Can I get a refund through this connector? -> no, Paycos refunds aren't currently supported for either account type - arrange refunds directly with Paycos
Not sure which account type to use? -> ask your Corefy account manager

Still looking for help connecting your Paycos account?

Please contact our support team!