Skip to content

Logo

MTB Bank

Supports in this guide: Payments, Payouts

Provider website: mtb.ua

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

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

Prerequisites: get from MTB Bank

Contact your MTB Bank account manager to get your account verified and receive credentials. The exact set depends on which account type you connect (see below).

UAH only.

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

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • Wallet ID
  • Partner token
  • API public key -> uploaded as a file
  • API secret key -> uploaded as a file
  • Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected MTB Bank H2H Merchant account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice - this is a card-to-wallet transfer, so customer.reference_id must be set to the recipient wallet ID on MTB Bank's side, not just an internal label. Card data itself is collected and submitted separately by Corefy's checkout/SDK layer, not as part of this request. Card, Apple Pay, and Google Pay are all supported on this same connection.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "6f1a2b3c-4d5e-4f60-8a71-9b2c3d4e5f60",
      "service": "payment_card_uah_hpp",
      "currency": "UAH",
      "amount": 100,
      "customer": {
        "reference_id": "100045821"
      }
    }
  }
}

Important

customer.reference_id is required and must be the recipient's MTB Bank wallet ID (sent as TransferC2W.RecipientWallet.ID).

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "a1b2c3d4-5e6f-4789-8a0b-1c2d3e4f5061",
      "service": "payment_card_uah_hpp",
      "currency": "UAH",
      "amount": 100,
      "customer": {
        "reference_id": "100045821",
        "name": "Ivan Petrenko",
        "individual_tax_id": "1234567890",
        "metadata": {
          "purpose_key": "Top-up of personal account"
        }
      }
    }
  }
}

Important

  • If customer.name is missing, the name parts sent to MTB Bank are simply left empty - no fake name is substituted.
  • customer.individual_tax_id, if present, is sent as the sender's INN/tax ID.

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_name_format -> optional, enumeration (LAST, FIRST, MIDDLE / FIRST, MIDDLE, LAST / LAST, MIDDLE, FIRST / LAST, FIRST / FIRST, LAST) - tells Corefy how to split customer.name into first/middle/last name parts before sending them to MTB Bank.
  • send_order -> optional, boolean - when enabled, sends your commerce invoice reference as the Order field.
  • payment_purpose -> optional, string - names a key in customer.metadata; if that key exists, its value is sent to MTB Bank as the payment's Purpose.

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)

  • PAYMENT_OPERATION_TYPE -> overrides the internal operation-type code used for a sale request
  • STATUS_OPERATION_TYPE -> overrides the internal operation-type code used for a status request
  • REFUND_OPERATION_TYPE -> overrides the internal operation-type code used for a refund request

Important

These three constants only take effect when the connection is not in Test Mode - while test_mode is enabled, Corefy always uses its own default operation-type codes regardless of what the constants are set to.

Refunds

MTB Bank supports partial refunds, but only one refund per payment (no multiple partial refunds against the same payment). The original payment's transaction ID is always required to process a refund.

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

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • Token
  • Private key -> uploaded as a file
  • Public key -> uploaded as a file
  • Terminal ID
  • Wallet ID
  • Test Mode -> (enable if you are using sandbox credentials)

Success

You have connected MTB Bank Provider account!

First request to Corefy API (MIN)

What it does: creates a payout-invoice for a card payout (account-to-card transfer).

Payout - MIN

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
      "service": "payment_card_uah",
      "currency": "UAH",
      "amount": 150,
      "customer": {
        "reference_id": "cus_123",
        "name": "Ivan Petrenko"
      },
      "fields": {
        "card_number": "4111111111111111"
      }
    }
  }
}

Important

  • fields.card_number is required.
  • The cardholder name sent to MTB Bank comes from fields.card_holder if provided, otherwise it falls back to customer.name.

Payout - MAX

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f70",
      "service": "payment_card_uah",
      "currency": "UAH",
      "amount": 150,
      "customer": {
        "reference_id": "cus_123",
        "name": "Ivan Petrenko",
        "individual_tax_id": "1234567890",
        "metadata": {
          "purpose_key": "Payout for order #4521"
        }
      },
      "fields": {
        "card_number": "4111111111111111",
        "card_holder": "IVAN PETRENKO"
      }
    }
  }
}

Important

  • customer.individual_tax_id, if present, is sent as the recipient's IPN/tax ID.
  • If no payout_purpose metadata key matches (see Options below), the payout's own reference_id is sent as the Purpose instead.

Extended request (MAX)

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

Options

  • payout_purpose -> optional, string, up to 16 characters - names a key in customer.metadata; if that key exists, its value is sent to MTB Bank as the payout's Purpose.
  • send_order -> optional, boolean - when enabled, sends the payout's own ID as the Order field.

Refunds

MTB Bank does not support refunds on Payouts.

Additional info

  1. Active reconciliation is available on both flows - Payments support both the asynchronous callback and an active status request; Payouts support an active status request.
  2. Apple Pay and Google Pay are supported on the Payments flow, alongside regular card payments.
  3. No recurring - this connector does not support saving/charging a token through Corefy.
  4. If your Corefy merchant profile has a company name, legal entity identifier, or IBAN on file, it is automatically included in both Payments and Payouts requests - no separate configuration needed.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify the keys and tokens for the selected environment (test_mode)
  • Payment rejected for the recipient wallet -> confirm customer.reference_id is the correct MTB Bank wallet ID, not just an internal customer identifier
  • Operation-type Constants seem to have no effect -> they are ignored while the connection is in Test Mode by design
  • Currency or service is not supported -> only UAH is available for this connector
  • Refund fails with multiple attempts -> only one refund per payment is allowed

Question

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