Skip to content

Logo

bill_line

Building technology behind payment products

Supports in this guide: Payments, Payouts

Provider website: billline.net

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

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

Choose account type

bill_line 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 redirect payments (customer redirected to a hosted payment page) or payouts -> choose Provider account

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

Prerequisites: get from bill_line

For H2H Merchant account:

  • Merchant ID -> Corefy field merchant_id -> where to find: bill_line backoffice / issued by bill_line manager.
  • Secret Key -> Corefy field secret_key -> where to find: bill_line backoffice / issued by bill_line manager.
  • API URL -> Corefy field api_url -> where to find: bill_line backoffice / issued by bill_line manager.

For Provider account:

  • Merchant ID -> Corefy field merchant_id -> where to find: bill_line backoffice / issued by bill_line manager.
  • Merchant Secret Key -> Corefy field merchant_secret_key -> where to find: bill_line backoffice / issued by bill_line manager.
  • API URL -> Corefy field api_url -> where to find: bill_line backoffice / issued by bill_line manager.
Payments processing (connect H2H Merchant account, create payment-invoice)

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

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

Choose Currency and Features. You can set these parameters according to available currencies and features for your bill_line account (RUB, UAH, USD, EUR, KZT, AZN, UZS confirmed), but it is necessary to check details of the connection with your Corefy account manager.

Success

You have connected bill_line 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 checkout/SDK layer, not as part of this request.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "8e3dbbb0-17af-4c9a-bedb-93bdac6900a2",
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 10
    }
  }
}

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "6795502c-e27d-4d07-85e0-93245aab9a3f",
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Smith",
        "email": "johnsmith@gmail.com",
        "phone": "+15551234567",
        "address": {
          "country": "DE",
          "region": "Berlin",
          "city": "Berlin",
          "full_address": "1 Main street",
          "post_code": "10115"
        }
      }
    }
  }
}

None of customer's fields are strictly required - if you omit email, phone, or the address fields, bill_line still receives a value for each one, since Corefy fills gaps with realistic auto-generated placeholder data rather than sending them blank. Send the real values if you want bill_line to see your actual customer's details. A CVV isn't required for UZS sales specifically - a fixed placeholder is used instead when the card doesn't carry one. This connector also supports RUB, UAH, USD, KZT, AZN, and UZS (use payment_card_<currency>_hpp as the service code).

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

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

Currently available options (2)

  • ignore_callback - tells Corefy to disregard bill_line's own callback notifications entirely.
  • send_user_id - sends your own customer.reference_id to bill_line as user_id.
ignore_callback

What it does: when enabled, Corefy ignores callback notifications sent by bill_line for this connection, relying on status checks/reconciliation instead.

When to use: enable only if instructed by bill_line or your Corefy account manager - for example if bill_line's callbacks for your account are unreliable or duplicated.

Default: false

Allowed values: true / false

send_user_id

What it does: when enabled, forwards customer.reference_id to bill_line as user_id on every sale request.

When to use: enable it if bill_line or your account manager asked you to identify customers by your own reference ID.

Default: false

Allowed values: true / false

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

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • Merchant ID
  • Merchant Secret Key
  • Payment Method -> select one: Payment Card, PIX Transfer, Google Pay, Apple Pay, or Openbanking
  • Currency -> select all that apply
  • Language -> language used on bill_line's hosted payment page
  • API URL
  • Test Mode -> (enable if you are using sandbox credentials)

Important

Payment Method is a single choice per connection - if you need more than one of Payment Card/PIX/Google Pay/Apple Pay/Openbanking, connect a separate Provider account for each one.

Success

You have connected bill_line Provider account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice and returns a redirect link to bill_line's hosted payment page.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "0dde9e79-2c64-4703-adaf-93d710633401",
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 10
    }
  }
}

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "reference_id": "7976b4ce-fadd-4585-baa0-6b02c65351dc",
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Smith",
        "email": "johnsmith@gmail.com",
        "phone": "+15551234567",
        "address": {
          "country": "DE",
          "city": "Berlin",
          "post_code": "10115",
          "full_address": "1 Main street",
          "region": "Berlin"
        }
      }
    }
  }
}

For plain card payments, none of customer's fields are strictly required - bill_line receives a generic placeholder identity (e.g. name "Ivan Ivanov", country UA) for anything you don't send, rather than a blank field. This connector also supports RUB, UAH, and USD for card payments, plus three other method families with their own service codes and fields - see Additional info for PIX, Open Banking, and Apple Pay/Google Pay.

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 -> provider may reject the request or apply its defaults (depends on provider)

Currently available constants (constant -> Corefy API field)

  • FIRST_NAME -> customer.name (first part)
  • LAST_NAME -> customer.name (second part)
  • COUNTRY -> customer.address.country
  • IP -> customer.metadata.ip
  • EMAIL -> customer.email
  • PHONE -> customer.phone
  • FULL_ADDRESS -> customer.address.full_address
  • CITY -> customer.address.city
  • POST_CODE -> customer.address.post_code
  • REGION -> customer.address.region
  • REFERENCE_ID -> customer.reference_id

Note

These constants only apply to the googlepay_eur_hpp and applepay_eur_hpp services - plain card/PIX/Openbanking payments use the generic placeholder fallback described above instead, with no Constants to configure.

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

Connect Provider account in Corefy Dashboard

Uses the same Provider account connection as Payments above.

First request to Corefy API (MIN)

What it does: creates a payout-invoice and sends funds to a card.

Payout - MIN

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "0dde9e79-2c64-4703-adaf-93d710633401",
      "service": "payment_card_eur",
      "currency": "EUR",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123"
      },
      "fields": {
        "card_number": "4111111111111111"
      }
    }
  }
}

Payout - MAX

POST /api/payout-invoices 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "7976b4ce-fadd-4585-baa0-6b02c65351dc",
      "service": "payment_card_eur",
      "currency": "EUR",
      "amount": 10,
      "customer": {
        "reference_id": "cus_123",
        "name": "John Smith"
      },
      "fields": {
        "card_number": "4111111111111111"
      }
    }
  }
}

fields.card_number is required. This connector also supports card payouts in RUB, UAH, AZN, and KZT. USD and KZT have extra requirements: USD additionally needs fields.card_exp_month/card_exp_year and a cardholder name (from customer.name); KZT additionally needs a cardholder name, and can route through a custom provider-side method code via the use_custom_method_code option and CUSTOM_METHOD_CODE constant below.

Options

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

Currently available options (1)

  • use_custom_method_code - lets a KZT payout override bill_line's own internal routing method code.
use_custom_method_code

What it does: for payment_card_kzt payouts only, replaces bill_line's own default routing method code with the value set in the CUSTOM_METHOD_CODE constant below.

When to use: enable only if instructed by bill_line or your Corefy account manager - most KZT payouts don't need this.

Default: false

Allowed values: true / false

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.

Currently available constants (constant -> Corefy API field)

  • CUSTOM_METHOD_CODE -> not a request-field fallback - only takes effect for payment_card_kzt payouts when use_custom_method_code is enabled above.

PIX payouts (BRL)

PIX payouts use different fields entirely - fields.cpf_number (the recipient's Brazilian tax ID) and fields.pix_key (the destination PIX key), with service pix_brl, instead of card_number: 

{
  "data": {
    "type": "payout-invoice",
    "attributes": {
      "reference_id": "08f5e97c-1170-4bda-9625-3bde3c6dcd20",
      "service": "pix_brl",
      "currency": "BRL",
      "amount": 100,
      "customer": {
        "reference_id": "cus_123"
      },
      "fields": {
        "cpf_number": "12345678909",
        "pix_key": "johnsmith@gmail.com"
      }
    }
  }
}

Additional info

H2H Merchant account:

  1. Callback routing. The callback endpoint is /billline/callback - register it in bill_line's own back-office.

Provider account:

  1. Callback routing is automatic for both Payments and Payouts - Corefy generates the callback URL per transaction, nothing to configure in bill_line's own back-office.
  2. PIX (Brazil) is available as its own Payments method (service pix_brl_hpp) alongside card payments - fields.cpf_number is an optional field for this flow (the payer's Brazilian tax ID).
  3. Open Banking (EUR) is available as its own Payments method (service openbanking_eur_hpp) - fields.bank_id selects which bank the customer is redirected to.

  4. Apple Pay and Google Pay are supported via their own dedicated services (applepay_eur_hpp, googlepay_eur_hpp).

    For more information, visit:

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify credentials for the selected environment and account type
  • Provider account: payment rejected for an unexpected method -> each Provider account connection is configured for exactly one Payment Method (Card/PIX/Google Pay/Apple Pay/Openbanking) - confirm you're using the service code that matches the connection's configured method
  • Currency or service is not supported -> confirm allowed currencies/features in your bill_line account and in Corefy
  • Missing customer data fields (wallet payments) -> set the Constants (see "Constants") or provide the fields in the API request
  • Not sure which account type to use? -> ask your Corefy account manager

Question

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