Skip to content

Logo

UPay

UPay - Trust. Simple. Fast.

Supports in this guide: Payments | Payouts

Provider website: upay.express

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

  1. Choose account type
  2. Get your credentials (from UPay)
  3. Connect in Dashboard
  4. Send an API request

Choose account type

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

  • If you do payments -> choose Provider account
  • If you do payouts -> choose Provider account

Both flows use the same Provider account: one connection serves payment and payout routes.

If you are not sure which one to use, confirm with your Corefy account manager.

Prerequisites: get from UPay

Contact your UPay account manager to get your account verified and receive the following credential.

  • API token -> Corefy field api_token.

Currently available currency: UAH.

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

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • API token -> api_token
  • Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected UPay Provider account!

First request to Corefy API

What it does: creates a payment-invoice. This is a card-to-card p2p transfer, not a redirect to a hosted page - UPay responds with a card number and cardholder name, and Corefy's checkout displays those details to the customer, who must transfer the exact amount to that card themselves. customer data is not part of this connector's request format at all.

Payment - Actual

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "1f2aa3ca-abd8-4741-980d-4017ed30cb8c",
      "service": "card_transfer_uah_invoice",
      "currency": "UAH",
      "amount": 100
    }
  }
}

Important

If UPay doesn't return a card number for the invoice, Corefy treats the payment as failed rather than showing an incomplete card to the customer.

Important

If the customer transfers a different amount than the invoice requested, UPay can still report the payment as successful. In that case Corefy records the amount UPay actually received, not the originally requested amount.

Options

Options are configured on the Corefy side and affect how Corefy builds provider requests or processes responses.

Currently available options (2)

  • treat_failed_status_as_final - changes whether a failed status from UPay is reported to Corefy as final or as pending
  • use_invoice_reference_id_as_custom_id - sends your own invoice reference ID to UPay as custom_id instead of Corefy's own payment number
treat_failed_status_as_final

What it does: by default, a failed status reported by UPay (this also covers UPay's expired, payment_expired and cancelled codes, which map to the same internal failed status) is reported to Corefy as pending, in case UPay updates it later. Enabling this option reports it as failed (final) right away instead. When to use: enable it if you'd rather see a final failed status immediately than wait for a possible later update from UPay. Default: false Allowed values: true, false

use_invoice_reference_id_as_custom_id

What it does: when enabled, Corefy sends your own invoice reference ID to UPay as custom_id, instead of Corefy's own payment number. When to use: if you need UPay's custom_id to match your own invoice reference rather than Corefy's internal payment number. Default: false Allowed values: true, false

Refunds

UPay 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

What it does: creates a payout-invoice, sending funds to a bank card.

Payout - Actual

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "2f8e6c71-4b3a-4e5d-9c21-7a6f1d0b8e4c",
      "service": "bank_transfer_uah",
      "currency": "UAH",
      "amount": 1000,
      "fields": {
        "card_number": "4111111111111111"
      }
    }
  }
}

Important

fields.card_number is required - it's the only recipient detail UPay needs. customer data is not part of this connector's request format.

Refunds

UPay does not support refunds.

Additional info

  1. Active reconciliation is available on both Payments and Payouts - Corefy can poll UPay's status endpoints in addition to receiving its callbacks.

  2. Callback signature verification is always enforced - UPay signs every callback with HMAC-SHA256 over the payload, keyed with your own api_token; Corefy rejects any callback whose signature doesn't match.

  3. Callback routing is handled automatically - Corefy generates the callback URL and sends it to UPay with every payment and payout request, so nothing has to be set up on UPay's side.

  4. Authentication is header-based - your API token is sent as the X-API-Token HTTP header on every request, not as a JSON field.

  5. Sandbox requests tell UPay the expected outcome - when Test Mode is enabled, Corefy adds an expected_status: success instruction to every payment and payout request, so sandbox transactions can complete predictably.

  6. No recurring - this connector does not support saving/charging a token through Corefy.

  7. No hardcoded fallback values - customer fields simply aren't part of this connector's request format on either flow, so there's nothing for Corefy to default when customer data is missing.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify the API token and the selected environment (test_mode)
  • Payment shows as pending even though UPay reports it failed -> this is expected unless you enable treat_failed_status_as_final
  • Payment fails immediately with no card details shown to the customer -> UPay didn't return a card number for that invoice; check your UPay account status/limits
  • Payout rejected -> confirm fields.card_number is present and valid; check UPay's own minimum/maximum amount limits for your account
  • Refund fails -> UPay does not support refunds through Corefy
  • Not sure which account type to use? -> ask your Corefy account manager

Question

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