Craftgate

Who should use this guideThis guide is intended for merchants who:

Use Payrails as a payment orchestrator
Use Craftgate for cards or YKB WorldPay in Türkiye
Have access to the Craftgate merchant panel

Create a Craftgate integration in Payrails

Log in to the Payrails portal.
Go to Settings → Integrations.
Select Add instance to create a new integration configuration.
Select the workspaces where this integration should be available.

About workspacesWorkspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.

Step 1: Choose the integration type

Select Payment.
Continue to the next step.

Step 2: Choose the provider

Select Craftgate.
Continue to the next step.

A screenshot showing Craftgate selected as the provider.

Step 3: Configure your Craftgate integration

What you’ll need from CraftgateBefore you begin, make sure you can log in to the Craftgate merchant panel. You’ll copy your API keys and callback keys there and set up a webhook. To add a payment method such as YKB WorldPay to your Craftgate account, contact Craftgate.

Integration instance name

An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for different regions, currencies, or business needs. Choose a clear, consistent name, as it is used in routing.

In Payrails

Enter an Instance name for your integration, for example merchant_craftgate.

A screenshot showing the integration instance name field.

Credentials

In Craftgate

In the Craftgate merchant panel, go to Settings → API Keys and copy the API key and secret key.
Go to Settings → Merchant Settings and copy the 3DS callback key and the merchant callback key.

In Payrails

Field	Value
API Key	Your Craftgate API key
Secret Key	Your Craftgate secret key. Payrails signs every request with it.
3DS Callback Key	Your 32-character 3DS callback key. Payrails uses it to verify 3D Secure callbacks.
APM Callback Key	Your merchant callback key. Payrails uses it to verify YKB WorldPay callbacks.
Webhook Key	Your Craftgate webhook key. Fill it in after you set up the webhook in the next section.

Fill in all the keys, so that Payrails verifies every callback and webhook from Craftgate. Payrails sends requests to the Craftgate sandbox in test mode and to the live environment in live mode, so use the keys for the matching environment.

A screenshot showing the Craftgate credential fields.

Payment methods

In Payrails

Select Card, YKB WorldPay or both.

A screenshot showing the Craftgate payment method selection.

Webhooks or notifications

Payrails uses provider webhooks or notifications to receive asynchronous payment status updates.

Create webhooks in the same mode (test or live) as your Payrails integration.

In Payrails

Copy the Notification URL shown under Account configuration at the top of the integration form.

In Craftgate

In the Craftgate merchant panel, go to Settings → Merchant Settings → Webhook.
Add the Payrails notification URL.
Copy the webhook key into the Webhook Key field in Payrails, and save both sides.

Request fields for Craftgate

Send these fields in the authorize request for card payments, in addition to the standard authorize fields. Required fields must be present for the payment to succeed. Payrails sends Optional fields to Craftgate when you include them. For more about meta fields, refer to Meta fields.

Field	Status	Description
`amount`	Required	Sent to Craftgate as the price, paid price and currency.
`instrument.data.bin`	Required	When `installments.count` is more than 1. Payrails uses it to price the installment plan.
`merchantReference`	Optional	Sent as the conversation ID.
`meta.order.description`	Optional	Sent as the item name.
`meta.clientContext.ipAddress`	Optional	Sent as the client IP.
`instrument.holderName`	Optional	Sent as the card holder. If you don’t send it, Payrails uses `meta.customer.name` and `meta.customer.lastName`.
`meta.customer.reference`, `meta.customer.email`, `meta.customer.phone`	Optional	Sent as buyer details for Craftgate fraud checks.
`meta.risk.merchantDefinedData.customFraudVariable`	Optional	Sent as the custom fraud variable.
`meta.risk.threeDSMode`	Optional	`Force` runs 3D Secure. Craftgate can also ask for 3D Secure when the bank requires it.
`installments.count`	Optional	Sent as the number of installments. Installment plans with interest need instant capture.
`instrument.storeInstrument`	Optional	Stores the card with Craftgate for later payments.

Enable the integration

In Payrails

Select Save account to enable the integration.
Confirm the integration shows as Enabled.

Your Craftgate integration is now ready to process payments.

Next steps

Run a test card payment in TRY in the Craftgate sandbox.
Verify that:
- The payment appears in the Craftgate merchant panel.
- The payment status updates correctly in Payrails.
Once verified in test mode, repeat the setup in live mode.

→ Continue to: Test a payment

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Create a Craftgate integration in Payrails

Step 1: Choose the integration type

Step 2: Choose the provider