canonical: https://jentic.com/apis/craftgate.io/craftgate

# Craftgate Payment API

Craftgate is a payment orchestration platform widely used in Turkey and Central Asia, and the Craftgate Payment API exposes its alternative payment methods (APM) flow for accepting Kaspi, PayPal, Klarna, and other regional wallets and BNPL providers. The API provides three endpoints: initialize an APM payment to redirect the buyer, complete the payment after the buyer returns from the wallet, and retrieve the final payment status. Authentication uses an API key, and both production and sandbox servers are available.

## For AI agents

Initialize, complete, and retrieve alternative payment method (APM) transactions on Craftgate for wallets like Kaspi, PayPal, and Klarna. Use when an agent needs to accept a regional or BNPL payment that is not a card charge.

## Scope

Does not handle card processing, refunds, or merchant onboarding KYC - use for alternative payment method (APM) initialization, completion, and status retrieval only.

## Capabilities

- Initialize an alternative payment method transaction and receive a redirect URL for the buyer
- Complete an APM payment after the buyer returns from the wallet or BNPL provider
- Retrieve the final status of an APM payment by paymentId
- Switch between production and sandbox environments using the same endpoint structure
- Support multiple wallets and BNPL providers including Kaspi, PayPal, and Klarna through a single APM flow

## Use cases

### Accept Kaspi Payments in Kazakhstan

An e-commerce checkout serving Kazakh shoppers calls POST `/payment/v1/apm-payments/init` with the order amount, currency, and apmType 'KASPI'. The response contains a redirect URL that sends the buyer to the Kaspi app to approve the charge. After the buyer returns, the merchant calls POST `/payment/v1/apm-payments/complete` and the order is marked paid. This adds a wallet that local shoppers prefer without a separate Kaspi integration.

Example prompt: Call POST `/payment/v1/apm-payments/init` with amount 25000, currencyCode 'KZT', and apmType 'KASPI', then redirect the buyer to redirectUrl from the response.

### Klarna Buy Now, Pay Later Checkout

A merchant offers Klarna at checkout for European customers. POST `/payment/v1/apm-payments/init` with apmType 'KLARNA' creates the transaction and returns the Klarna hosted page URL. Once Klarna redirects the buyer back, `/apm-payments/complete` confirms the captured payment. The single Craftgate flow saves the merchant from running two separate APM integrations.

Example prompt: POST to `/payment/v1/apm-payments/init` with apmType 'KLARNA', amount 19900, currency 'EUR', then complete the payment with `/apm-payments/complete` using the returned token.

### Reconciliation and Status Checks

A finance team reconciles APM transactions overnight. For each pending paymentId, the job calls GET `/payment/v1/apm-payments/{paymentId}` to retrieve the final status (approved, declined, or expired) and updates the order management system accordingly. This catches abandoned wallet payments that the buyer never completed.

Example prompt: For each unresolved paymentId in today's APM batch, call GET `/payment/v1/apm-payments/{paymentId}` and update the OMS with the returned status.

### Agent-Driven Multi-Wallet Checkout

An AI checkout agent picks the right alternative payment method for each shopper based on their region and basket. It calls Craftgate's APM init endpoint with the chosen apmType, hands the buyer the redirect URL, and confirms with /complete on return. Through Jentic, the agent finds the right Craftgate operation by intent and uses the API key without seeing it in plain text.

Example prompt: Search Jentic for 'initialize alternative payment method on craftgate', execute POST `/payment/v1/apm-payments/init` with the shopper's chosen apmType, and hand back the redirect URL.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/payment/v1/apm-payments/init` | Initialize an alternative payment method transaction |
| POST | `/payment/v1/apm-payments/complete` | Complete an APM payment after the buyer redirect |
| GET | `/payment/v1/apm-payments/{paymentId}` | Retrieve the final status of an APM payment |

## Key resources

- **APM Payments** — Initialize, complete, and retrieve alternative payment method transactions across wallets and BNPL providers

## Why Jentic

- **Setup:** Wiring Craftgate by hand means managing its API-key header and sequencing the init then complete calls that drive an alternative-payment flow yourself. Through Jentic you install once, import Craftgate from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Craftgate initializes and completes payments through collection paths and the request body, with the payment id only in the read path (`/payment/v1/apm-payments/{paymentId}`), so scope the agent to the operations it needs, such as initializing a payment or reading its status. You leave out completion unless the agent needs it.
- **Credential handling:** Your Craftgate API key is stored once, encrypted, by your own Jentic One instance and injected as the request header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'start a Kaspi payment' or 'initialize an alternative payment', and Jentic returns the matching Craftgate operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Stripe API** — Stripe is a global payment processor that supports cards, wallets, and BNPL through Payment Intents.
- **Adyen Checkout API** — Adyen Checkout supports a wide range of local payment methods through a single integration.
- **Mollie API** — Mollie offers European-focused payment methods including iDEAL and Klarna.
- **PayPal Orders API** — PayPal Orders is the underlying flow for PayPal as one of the APMs Craftgate routes.

## FAQ

### What authentication does the Craftgate Payment API use?

Craftgate uses an API key sent as a header on each request. Through Jentic, the API key is stored encrypted in the vault and added to outgoing requests at execution time, so it never appears in the agent's prompt or logs.

### Can I accept Kaspi payments through the Craftgate API?

Yes. POST `/payment/v1/apm-payments/init` with apmType 'KASPI' returns a redirect URL that takes the buyer to the Kaspi app to approve the charge. After the redirect back, POST `/payment/v1/apm-payments/complete` finalises the transaction.

### Does Craftgate support a sandbox environment?

Yes. The same three endpoints are available at https://sandbox-api.craftgate.io for end-to-end testing. Switch base URL only - request and response shapes are identical to production.

### How do I check the status of an APM payment through Jentic?

Search Jentic for 'retrieve craftgate payment status', load GET `/payment/v1/apm-payments/{paymentId}`, and execute with the paymentId. The response contains the final status that should be reflected in the order management system.

### What are the rate limits for the Craftgate API?

The OpenAPI spec does not declare numeric rate limits. Craftgate enforces fair-use limits in production. Production integrations should retry on 429 responses with exponential backoff and avoid synchronous polling loops.

### Which alternative payment methods does this Craftgate spec cover?

This APM spec covers methods including Kaspi (Kazakhstan), PayPal, and Klarna, all flowing through the same three init/complete/retrieve endpoints by setting different apmType values. Card payments and refunds live on separate Craftgate APIs.

### Can I limit what my agent is allowed to do with the Craftgate Payment API?

Yes. Because you run Jentic One yourself, your own rules decide which Craftgate operations the agent can call and which credentials it may use. This API has three operations, so you can grant only POST `/payment/v1/apm-payments/init` to start a payment and GET `/payment/v1/apm-payments/{paymentId}` to read its status, while withholding POST `/payment/v1/apm-payments/complete` unless the agent needs to finalise the charge. The stored API key is injected at execution time under those same rules, so a read-only agent can never trigger a completion.