AI-Assisted Integration

Agent-ready implementation guide

Let your coding agent build the integration from the live docs.

Copy one of these prompts into Codex, Cursor, Claude Code, GitHub Copilot, or another coding agent. The prompt tells the agent to inspect this project's OpenAPI schemas, discover the merchant capabilities available to your account, and implement the integration without copying currencies, banks, methods, or payloads from examples.

Best starting pointFull Backend Integration

Use when the merchant backend does not have pay-in, webhook, and reconciliation support yet.

Keep Secrets Out of AI Tools

Do not paste real API keys, production secrets, signed URLs, webhook URLs with tokens, or customer data into an AI tool. Use environment variable names, secret manager references, and placeholder values.

Pick the Task

BuildFull backend integration

API client, pay-in, optional pay-out, Payment Page, webhooks, reconciliation, storage, and tests.

AddPayment Page flow

Redirect customers to the hosted page after pay-in creation and preserve local order state.

ImplementWebhook receiver

Raw-body signature verification, idempotent status updates, and callback history.

ReviewExisting integration

Security, capability discovery, idempotency, reconciliation, and missing tests.

What to Give Your Agent

Documentation

Current developer portal URL or exported OpenAPI files for this exact project.

Target flow

Pay-in, Payment Page, pay-out, webhook receiver, reconciliation, or audit.

Code context

Backend repository, framework, database model, and where orders or payments are stored.

Secret names

Environment variable names or secret-manager references, never real secret values.

How the Agent Should Work

1

Read current docs

The agent must inspect this project portal or exported OpenAPI files before writing code.

2

Discover capabilities

Currency, bank, method, and locale values must come from this project, environment, and merchant account.

3

Implement server-side

The merchant API key, signed requests, and webhook verification stay on the backend.

4

Prove it

The result must include tests for signatures, duplicates, unsupported capabilities, and reconciliation.

What the Agent Must Read First

Examples are intentionally generic. The agent must resolve real values from the current project docs and API.

Need	Source
API authentication	Authentication page and current OpenAPI headers
Merchant currencies and rates	GET /payment/trading/currency
Merchant pay-in bank options	GET /payment/trading/banks
Merchant pay-in methods	Current generated Pay-In docs and current OpenAPI schema
Payment Page locale support	Current pay-in request schema and project docs
Pay-in request fields	Current schema for POST /payment/trading/pay-in
Pay-out request fields	Current schema for POST /payment/trading/pay-out
Endpoint signing requirements	Authentication page plus current OpenAPI operation headers
Webhook URL setup	Merchant Panel/API configuration docs and environment config
Trade lookup by platform id	GET /payment/trading/{id}
Trade lookup by merchant id	GET /payment/trading/external/{id}
Webhook verification	Webhook and Authentication signature sections

The agent should

• read the current project schemas before coding;
• use discovery endpoints for merchant capabilities;
• store platform trade ids and merchant transaction ids;
• verify webhook signatures over the raw body;
• make all status updates idempotent.

The agent must not

• copy currencies, banks, methods, or locales from examples;
• create static enums, allowlists, seed data, tests, or dropdowns from sample values;
• use another project or environment as source of truth;
• put x-api-key in frontend or mobile code;
• log secrets, signatures, raw sensitive payloads, or payment details;
• apply webhook side effects more than once.

Capability Scope

Currencies, banks, methods, locales, and route-specific fields are scoped to the current project, environment, and merchant account. If the docs, schema, and runtime discovery disagree, the agent should stop and ask for clarification instead of guessing.

Fail Closed on Unknown Capabilities

If no authoritative source exists for a currency, bank, method, locale, or route-specific field, the generated integration should fail with a clear configuration error. It must not silently fall back to example values.

Build a Full Backend Integration

Use this when the merchant backend needs the complete integration.

You are integrating the Merchant Payment API into my backend.

Mission:
Build a production-ready server-side integration using the current developer
portal and OpenAPI schemas as the source of truth. Do not invent endpoints,
fields, statuses, currencies, banks, payment methods, locales, or webhook
payloads.

Inputs I will provide:
- Current developer portal URL or exported OpenAPI files.
- API base URL as an environment variable name.
- API key as an environment variable or secret manager reference.
- My backend framework, database, and existing order/payment model.
- Whether this integration needs pay-in only or both pay-in and pay-out.

First actions:
1. Inspect the current docs and schemas for:
   - GET /payment/trading/currency
   - GET /payment/trading/banks
   - POST /payment/trading/pay-in
   - POST /payment/trading/pay-out, only if payouts are needed
   - GET /payment/trading/{id}
   - GET /payment/trading/external/{id}
2. Inspect generated project docs and OpenAPI enums for method-specific fields,
   Payment Page locale values, and endpoint-level signing requirements.
3. Identify required headers, request fields, response fields, and error shapes.
4. Identify which values are runtime-discovered and must not be hardcoded.
5. If the docs, schema, and runtime discovery conflict, stop and ask me before
   guessing.

Security rules:
1. Keep x-api-key only on the backend.
2. Never expose merchant credentials in frontend or mobile code.
3. Do not log API keys, signatures, raw sensitive webhook payloads, payment
   details, customer PII, or secrets.
4. When logging failures, prefer internal order ids, platform trade ids,
   externalTransactionId, and correlation ids instead of raw payloads.
5. Use environment variables or a secret manager for all credentials.
6. Support merchant API IP whitelist requirements if this account uses them.
7. Inspect the OpenAPI and authentication docs for each endpoint to determine
   whether outbound x-signature is required. If required, sign the exact JSON
   request body bytes with HMAC-SHA256(body, API_KEY), send x-signature, and
   test that signing is stable for the serialized body actually sent.

Capability rules:
1. Treat currencies, banks, methods, locales, and method-specific fields as
   project/environment/merchant scoped.
2. Discover merchant currencies and rates with GET /payment/trading/currency.
3. Discover merchant pay-in banks with GET /payment/trading/banks.
4. Validate requested currency, bank, method, and locale against discovered
   capabilities or current schemas before creating a transaction.
5. Do not use another brand, project, environment, screenshot, or example as the
   capability source.
6. Do not create static enums, switch statements, allowlists, seed data, tests,
   or frontend dropdown options from example values. Build selectable
   currencies, banks, methods, and locales only from the current project API,
   generated project docs, current OpenAPI schema, or merchant configuration.
7. If no authoritative source exists for a capability, fail closed with a clear
   configuration or integration error instead of guessing.

Pay-in requirements:
1. Implement server-side pay-in creation.
2. For each merchant order, generate one stable externalTransactionId before
   the first API call, store it with a unique database constraint, and reuse it
   for retries of the same order.
3. Do not create a second platform transaction when a local order already has a
   platform trade id or externalTransactionId.
4. Store my internal order id, platform trade id, externalTransactionId, type,
   status, fiatAmount, fiatCurrency, method, bank, and timestamps.
5. Redirect the customer to externalPaymentPageUrl when it is returned.
6. Support paymentPageConfig overrides only when the current schema supports
   them and the business flow needs them.
7. Pass payerInfo when my application has trustworthy data.
8. Store amount and currency fields safely for accounting; do not use floating
   point math for balances or settlement effects.
9. Handle API errors without exposing sensitive platform details to customers.

Pay-out requirements, only if I ask for payouts:
1. Inspect the current pay-out schema before implementing.
2. Send method-specific requisite fields only when the current schema supports
   them.
3. Store platform trade id, externalTransactionId, status, amount, currency,
   method, bank, and timestamps.
4. Handle insufficient balance, unavailable payout route, validation errors, and
   duplicate externalTransactionId safely.
5. Do not invent status transitions. If the current docs describe payout route
   reassignment or retry states, model them explicitly and keep repeated,
   reverted, or out-of-order states idempotent.

Webhook requirements:
1. Implement a webhook endpoint on my backend.
2. Read the raw request body before JSON parsing.
3. Verify x-signature with HMAC-SHA256(rawBody, API_KEY).
4. Compare signatures using a timing-safe comparison.
5. Validate that x-signature is present, hex encoded, and the same byte length
   as the computed digest before timing-safe comparison. Return a controlled
   4xx response for malformed signatures; do not throw uncaught exceptions.
6. Reject missing or invalid signatures.
7. Process callbacks idempotently.
8. Duplicate callbacks must not duplicate accounting, balance, fulfillment, or
   order effects.
9. Store enough callback history to debug delivery and state transitions.
10. Do not assume statuses always move in one direction. Use the current status
    docs and reconciliation path for reassignment, retry, repeated, or
    out-of-order updates.

Reconciliation requirements:
1. Implement lookup by platform trade id using GET /payment/trading/{id}.
2. Implement lookup by externalTransactionId using
   GET /payment/trading/external/{id}.
3. Add a reconciliation job or admin action for missed, duplicate, failed, or
   uncertain webhooks.
4. Make reconciliation update local state idempotently.

Expected output:
1. API client/config module.
2. Pay-in creation service.
3. Payment Page redirect handling.
4. Pay-out creation service if requested.
5. Webhook receiver with raw-body signature verification.
6. Reconciliation logic.
7. Database/model changes if needed.
8. Tests for signature verification, duplicate webhooks, duplicate
   externalTransactionId, unsupported capabilities, and reconciliation.
9. Retry behavior proving that the same merchant order reuses the stored
   externalTransactionId and cannot create duplicate platform transactions.
10. Environment variables needed, without real secret values.
11. A short production readiness checklist.

Add Payment Page Redirect

Use this when pay-in creation exists and the customer handoff needs to be added or tightened.

You are adding hosted Payment Page support to my existing Merchant API pay-in
integration.

Mission:
Redirect customers to the hosted Payment Page safely after server-side pay-in
creation. Use the current project documentation and OpenAPI schema as the source
of truth. Do not hardcode currencies, banks, payment methods, locales, domains,
or redirect behavior from examples.

First actions:
1. Inspect POST /payment/trading/pay-in request and response schemas.
2. Confirm how externalPaymentPageUrl is returned.
3. Confirm whether paymentPageConfig is available in the current schema.
4. Confirm valid locale values from the current schema if locale override is
   needed.

Implementation requirements:
1. Keep all Merchant API calls on the backend.
2. Store platform trade id and externalTransactionId before redirecting the
   customer.
3. Redirect to externalPaymentPageUrl only after successful pay-in creation.
4. If paymentPageConfig is used, make success_redirect, error_redirect,
   supportLink, and locale configurable from my backend.
5. Validate locale against the current project schema before sending it.
6. Pass payerInfo from the actual customer request context, not server defaults
   or test fixtures. Preserve customer IP, user agent, user id, and fingerprint
   when available, and document proxy/header assumptions.
7. Preserve a reconciliation path for customers who close the browser, return
   late, or never reach the success/failure URL.

Expected output:
- Updated pay-in flow.
- Payment Page redirect handler.
- Configuration/env vars needed.
- Tests for successful redirect, missing externalPaymentPageUrl, invalid locale,
  failed pay-in creation, and reconciliation after redirect.
- Short notes about customer return URLs and webhook reconciliation.

Implement a Webhook Receiver

Use this when transaction creation exists and callbacks need to be implemented correctly.

You are implementing the Merchant API webhook receiver in my backend.

Mission:
Build a secure, idempotent webhook receiver using the current Webhook and
Authentication documentation as the source of truth. Do not invent headers,
signature algorithms, payload fields, or statuses.

Security and parsing:
1. Read the raw request body before JSON parsing.
2. Compute HMAC-SHA256(rawBody, API_KEY).
3. Compare the computed signature with x-signature using a timing-safe
   comparison.
4. Validate that x-signature is present, hex encoded, and the same byte length
   as the computed digest before timing-safe comparison.
5. Return a controlled 4xx response for malformed signatures; do not throw
   uncaught exceptions.
6. Reject missing or invalid signatures.
7. Do not log raw payloads that may contain payment details or customer PII.

Business logic:
1. Parse the webhook payload only after signature verification succeeds.
2. Identify the transaction by platform trade id and/or externalTransactionId.
3. Process status changes idempotently.
4. Duplicate callbacks must not duplicate accounting, balance, fulfillment, or
   order effects.
5. Store callback delivery metadata for support and reconciliation.
6. Add a fallback reconciliation path using GET /payment/trading/{id} and
   GET /payment/trading/external/{id}.
7. If a callback references an unknown local order, use a controlled
   reconciliation path instead of silently accepting it.
8. Do not assume statuses always move in one direction. Use current status docs
   and reconciliation for reassignment, retry, repeated, or out-of-order
   updates.

Tests:
1. Valid signature is accepted.
2. Invalid signature is rejected.
3. Signature verification uses the exact raw body bytes.
4. Malformed, non-hex, or length-mismatched signatures return controlled 4xx.
5. Duplicate callback is safe.
6. Out-of-order or repeated status update is safe.
7. Unknown local order triggers reconciliation or a controlled error path.

Expected output:
- Webhook route/controller.
- Raw-body middleware/config if needed.
- Signature verification utility.
- Idempotent status update logic.
- Callback history storage if needed.
- Tests.

Audit an Existing Integration

Use this when the merchant already has code and wants an agent to review it.

You are auditing my existing Merchant API integration.

Mission:
Review my code against the current developer portal and OpenAPI schemas. Focus
on correctness, security, capability discovery, idempotency, reconciliation, and
production readiness.

Audit checklist:
1. API key is never exposed to frontend or mobile code.
2. API base URL and credentials are configurable per environment.
3. The integration does not hardcode currencies, banks, methods, or locales from
   examples.
4. Capability checks use the current project API and schemas.
5. For every supported currency, bank, method, and locale used by the
   integration, the exact source is documented: discovery endpoint response,
   current generated project docs, OpenAPI schema, or merchant configuration.
6. Any value copied from examples, screenshots, tests, another brand, or another
   environment is flagged as a blocker.
7. Pay-in creation uses one stable externalTransactionId per merchant order and
   reuses it for retries.
8. Pay-in flow stores platform trade id before customer redirect.
9. Payment Page handling uses externalPaymentPageUrl correctly.
10. Pay-out code, if present, follows the current pay-out schema and validates
   method-specific requisite fields.
11. Webhook handler verifies x-signature over the raw request body.
12. Signature comparison is timing-safe and handles malformed signatures safely.
13. Webhook processing is idempotent.
14. Duplicate callbacks cannot duplicate accounting, balance, fulfillment, or
    order effects.
15. Reconciliation exists through GET /payment/trading/{id} and
    GET /payment/trading/external/{id}.
16. Logs and errors do not expose API keys, signatures, customer PII, or full
    sensitive payment details.
17. Tests cover signature verification, duplicate callbacks, duplicate
    externalTransactionId, unsupported capabilities, and reconciliation.

Expected output:
- Findings ordered by severity.
- File and line references.
- Concrete code fixes where safe.
- Missing tests.
- Production readiness risks.
- A capability-source table for all currencies, banks, methods, and locales
  used by the integration.

Agent Review Checklist

Before merging agent-generated code, review it against these launch gates.

Security

• x-api-key stays server-side only;
• outbound x-signature is implemented where required;
• merchant API egress IPs are known and whitelisted if the account uses IP allowlisting;
• logs exclude API keys, signatures, PII, raw requisites, and full sensitive payloads;
• logs keep useful correlation ids without exposing sensitive data;
• required environment variables are documented without real secrets.

Capabilities

• currencies, banks, methods, and locales come from current sources;
• no static examples are used for enums, allowlists, seed data, tests, or frontend dropdowns;
• capability discovery failures fail closed with clear errors.

Transactions

• each merchant order has one stored externalTransactionId reused for retries;
• platform trade ids are stored before customer redirect;
• amount and currency values use decimal/string-safe handling, never floating point math for accounting effects.

Webhooks and Ops

• webhook URL is HTTPS, reachable, configured, and monitored;
• signatures are verified from raw body with malformed-signature tests;
• callbacks and reconciliation are idempotent;
• status handling covers repeated, reverted, reassigned, and out-of-order updates when the current docs allow them;
• missed, duplicate, out-of-order, and uncertain callbacks have an operator path.