Skip to content

Logo

Ryvyl

Supports in this guide: Payments

Provider website: ryvyl.com

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

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

Choose account type

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

  • If you do card payments -> choose H2H Merchant account

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

Prerequisites: get from Ryvyl

Get the following values for your Ryvyl project/account:

  • Access Token -> Corefy field access_token -> where to find: Ryvyl backend UI, under Administration > Account data > Merchant/Channel Info
  • Entity ID -> Corefy field entity_id -> where to find: Ryvyl backend UI, under Administration > Account data > Merchant/Channel Info
Payments processing (connect H2H Merchant account, create payment-invoice)

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • Access Token
  • Entity ID
  • 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 Ryvyl account, but it is necessary to check details of the connection with your Corefy account manager.

Success

You have connected Ryvyl H2H Merchant 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": {
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 100,
      "customer": {
        "reference_id": "55041b5b-adfd-4073-a92b-fd8b495a4cc1"
      },
      "reference_id": "86e68af6-6b95-4cc0-be16-e4df8044604c"
    }
  }
}

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "service": "payment_card_usd_hpp",
      "currency": "USD",
      "amount": 100,
      "customer": {
        "reference_id": "bc75bc54-5023-4f98-8c0d-ec5ed7e8f380",
        "name": "John Smith",
        "email": "johnsmith@gmail.com",
        "address": {
          "country": "US",
          "city": "Los Angeles",
          "post_code": "90001",
          "street": "1st Street 1"
        }
      },
      "reference_id": "08f5e97c-1170-4bda-9625-3bde3c6dcd20"
    }
  }
}
None of the customer fields above reach Ryvyl unless the include_customer_data option (see Options) is enabled — with it off (the default), Corefy sends no customer/billing data to Ryvyl at all, regardless of what's in the request. Ryvyl also supports EUR and GBP (use payment_card_eur_hpp/payment_card_gbp_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)

  • include_sender_data - sends your own merchant business details (not the customer's) to Ryvyl
  • include_customer_data - sends the customer's billing details (name, address) to Ryvyl
include_sender_data

What it does: includes your merchant account's own business details (company name, city, country, IBAN, street) in the request sent to Ryvyl — this describes your business, not the customer.

When to use: enable it if Ryvyl requires sender/originator details for your specific payment flow (e.g. remittance-style methods).

Default: "false"

Allowed values: true, false

include_customer_data

What it does: includes the customer's billing details (first/last name split from customer.name, email, and billing address) in the request sent to Ryvyl. With this option disabled, none of the customer fields in your request reach Ryvyl.

When to use: enable it if Ryvyl requires or benefits from billing/customer details for approval rates — some payment flows (e.g. 3DS v2) may require a billing address to work correctly.

Default: "false"

Allowed values: true, false

Additional info

  1. Ryvyl doesn't send asynchronous callbacks for this connection — Corefy relies on status reconciliation (polling) instead. Don't expect a webhook-driven status update; check the transaction status via the API if you need the latest state immediately.
  2. When Test Mode is enabled, Corefy requests Ryvyl's acquirer test system specifically (not a generic simulator) — this matches how your test credentials are provisioned.
  3. Your merchant account's own profile website is sent to Ryvyl automatically with every request — there's no separate field to override it per-transaction.

FAQ / Troubleshooting

  • Invalid credentials / auth error -> verify credentials for the selected environment and account type
  • Currency or service is not supported -> confirm allowed currencies/features in your Ryvyl account and in Corefy
  • Customer/billing data not reaching Ryvyl -> enable the include_customer_data option (see Options) — it's off by default
  • Not sure which account type to use? -> ask your Corefy account manager

Question

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