Skip to content

Logo

Cardiful New

Supports in this guide: Payments

Provider website: pay.tech (paytech — the payment gateway platform Cardiful New runs on)

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

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

Choose account type

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

  • If you do card payments (H2H, card data sent directly) -> choose H2H Merchant account
  • If you do local/alternative payment methods (Apple Pay, Google Pay, Skrill, Paysafecard, Rapid Transfer, Sofort, Multibanco, Neteller, EPS, MyBank, ePay.bg, MB WAY, Open Banking) — customer redirected to a hosted payment page -> choose Provider account

These are two separate credential sets — connecting one doesn't connect the other. If you are not sure which one to use, confirm with your Corefy account manager.

Prerequisites: get from Cardiful New

Cardiful New issues separate credentials for each account type below.

For H2H Merchant account:

  • API Key -> Corefy field api_key -> where to find: Cardiful New backoffice / issued by Cardiful New manager
  • Signing Key -> Corefy field signing_key -> where to find: Cardiful New backoffice / issued by Cardiful New manager, used to verify callback signatures
  • API URL -> Corefy field api_url -> only needed to override the default sandbox/live host

For Provider account:

  • API Key -> Corefy field api_key -> where to find: Cardiful New backoffice / issued by Cardiful New manager
  • Signing Key -> Corefy field signing_key -> where to find: Cardiful New backoffice / issued by Cardiful New manager, used to verify callback signatures
Payments processing (connect H2H Merchant account, create payment-invoice)

Connect H2H Merchant account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • API Key
  • Signing Key
  • API URL -> (optional — override the default sandbox/live host)
  • 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 Cardiful New account, but it is necessary to check details of the connection with your Corefy account manager.

Success

You have connected Cardiful New 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_eur_hpp",
      "currency": "EUR",
      "amount": 100,
      "customer": {
        "reference_id": "55041b5b-adfd-4073-a92b-fd8b495a4cc1"
      },
      "reference_id": "86e68af6-6b95-4cc0-be16-e4df8044604c"
    }
  }
}
customer.email is optional — Corefy forwards it if present, falling back to the EMAIL constant below otherwise.

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "service": "payment_card_eur_hpp",
      "currency": "EUR",
      "amount": 100,
      "customer": {
        "reference_id": "bc75bc54-5023-4f98-8c0d-ec5ed7e8f380",
        "name": "John Smith",
        "email": "johnsmith@gmail.com",
        "phone": "+15551234567",
        "date_of_birth": "1990-05-14",
        "address": {
          "country": "DE",
          "region": "Berlin",
          "city": "Berlin",
          "post_code": "10115",
          "full_address": "1st Street 1"
        }
      },
      "reference_id": "08f5e97c-1170-4bda-9625-3bde3c6dcd20"
    }
  }
}
customer.address.country is sent to Cardiful New twice, for two different purposes: as the citizenship country and as the billing address country — both are sourced from this one field, there's no separate way to set them differently. Cardiful New also supports USD, AUD, GBP, and CAD (use payment_card_<currency>_hpp as the service code, in lowercase).

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 (4)

  • ignore_callback - suppresses processing of callbacks received from Cardiful New
  • finalize_by_protocol - forces certain pending-like provider states to a final failed status instead of leaving them pending
  • save_provider_instant_token - tokenizes the card on the first Sale, for later recurring/merchant-initiated payments
  • send_additional_data - forwards metadata.additional_parameters from the request to Cardiful New
ignore_callback

What it does: when enabled, Corefy ignores callbacks received from Cardiful New instead of processing them.

When to use: if you rely only on reconciliation/status checks and don't want callback-driven updates for this connection.

Default: "false"

Allowed values: true, false

finalize_by_protocol

What it does: Cardiful New doesn't guarantee that a failed status is final — it can later change to success on their side. When this option is enabled, Corefy treats those states as a final failure immediately instead of waiting, so you won't see a transaction flip status after being reported as failed.

When to use: enable it if you'd rather have an immediate, final failed status than risk a late status change from Cardiful New.

Default: "false"

Allowed values: true, false

save_provider_instant_token

What it does: tokenizes the card on the first Sale, allowing later recurring/merchant-initiated payments without collecting card data again.

When to use: enable it if you plan to charge this customer again later using a saved token.

Default: "false"

Allowed values: true, false

send_additional_data

What it does: forwards the contents of metadata.additional_parameters (a JSON object or JSON-encoded string) from your request to Cardiful New as-is, when your provider configuration requires extra data beyond the standard fields.

When to use: only if Cardiful New or your Corefy account manager has told you specific extra parameters are needed for your setup.

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.

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
  • LAST_NAME -> customer.name
  • EMAIL -> customer.email
  • PHONE -> customer.phone
  • DATE_OF_BIRTH -> customer.date_of_birth
  • CITIZENSHIP_COUNTRY_CODE -> customer.address.country
  • COUNTRY_CODE -> customer.address.country
  • CITY -> customer.address.city
  • STATE -> customer.address.region
  • POSTAL_CODE -> customer.address.post_code
  • FULL_ADDRESS -> customer.address.full_address

Note

CITIZENSHIP_COUNTRY_CODE and COUNTRY_CODE are two independent constants that both fall back the same request field (customer.address.country), matching the two separate provider-side fields they back.

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

Connect Provider account in Corefy Dashboard

Step 1 - Open connection form

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

Step 2 - Fill in fields and select settings

  • API Key
  • Signing Key
  • 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 Cardiful New account, but it is necessary to check details of the connection with your Corefy account manager.

Success

You have connected Cardiful New Provider account!

First request to Corefy API (MIN)

What it does: creates a payment-invoice. This is a redirect flow — the customer is sent to a hosted page to complete the payment with their chosen method.

Payment - MIN

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "service": "skrill_eur_hpp",
      "currency": "EUR",
      "amount": 100,
      "customer": {
        "reference_id": "55041b5b-adfd-4073-a92b-fd8b495a4cc1"
      },
      "reference_id": "86e68af6-6b95-4cc0-be16-e4df8044604c"
    }
  }
}
customer.email is optional here too — it's forwarded if present, otherwise sent as null (this account type has no Constants to fall back to).

Payment - MAX

POST /api/payment-invoices 

{
  "data": {
    "type": "payment-invoice",
    "attributes": {
      "service": "skrill_eur_hpp",
      "currency": "EUR",
      "amount": 100,
      "customer": {
        "reference_id": "bc75bc54-5023-4f98-8c0d-ec5ed7e8f380",
        "name": "John Smith",
        "email": "johnsmith@gmail.com",
        "phone": "+15551234567",
        "date_of_birth": "1990-05-14",
        "address": {
          "country": "DE",
          "region": "Berlin",
          "city": "Berlin",
          "post_code": "10115",
          "full_address": "1st Street 1"
        },
        "metadata": {
          "website_url": "https://example.com"
        }
      },
      "reference_id": "08f5e97c-1170-4bda-9625-3bde3c6dcd20"
    }
  }
}
customer.metadata.website_url is sent to Cardiful New on every request; if not provided, Corefy falls back to the merchant account's own profile website.

Cardiful New supports these payment methods via their own service codes (pattern <method>_<currency>_hpp): applepay/googlepay (EUR, USD), and paysafecard/rapidtransfer/skrill/bank_transfer_klarna (Sofort)/multibanco/neteller/eps/mybank2/epaybg/mb_way/openbanking (EUR, USD, AUD, GBP, or CAD) — confirm with your Corefy account manager which 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

Options

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

Currently available options (2)

  • finalize_by_protocol - forces certain pending-like provider states to a final failed status instead of leaving them pending
  • send_payment_method - includes the selected payment method code in the request to Cardiful New
finalize_by_protocol

What it does: Cardiful New doesn't guarantee that a failed status is final — it can later change to success on their side. When this option is enabled, Corefy treats those states as a final failure immediately instead of waiting, so you won't see a transaction flip status after being reported as failed.

When to use: enable it if you'd rather have an immediate, final failed status than risk a late status change from Cardiful New.

Default: "false"

Allowed values: true, false

send_payment_method

What it does: includes the payment method code (derived from the service you selected, e.g. SKRILL, APPLEPAY) in the request sent to Cardiful New.

When to use: leave it enabled (the default) unless Cardiful New or your Corefy account manager has told you to omit it for your setup.

Default: "true"

Allowed values: true, false

Note

No Corefy-side Constants apply to this account type — there's no Dashboard fallback for customer/billing fields here, only what's sent in the request.

Additional info

  1. Callback routing is handled automatically (Corefy generates the callback URL per transaction) — signature validation is applied on both account types, using an HMAC-SHA256 hash of the callback body computed with your Signing Key.

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 Cardiful New account and in Corefy
  • Missing customer data fields -> set constants (H2H Merchant account only, see "Constants") or provide fields in the API request
  • Not sure which account type to use? -> ask your Corefy account manager

Question

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