Quick Start

Use this page to run your first payment or payout order with the DEEPayment SDK. For the complete field set, open API Reference by order type, country, and method.

Minimum integration loop: generate your key pair, configure the SDK, create an order, receive and verify a webhook, and query the order when you need confirmation. The SDK handles Ed25519 signing, Content-Digest, and X25519 body encryption; you never build those headers by hand.

Prerequisites

API host

Send production requests to https://panama.deepayment.com/api/v1. The SDK takes the origin only, without /api/v1.

Access Key

Public merchant identifier issued at onboarding.

Merchant Ed25519 key pair

Generate it yourself. Upload the public key in the merchant portal and keep the private key on your servers.

Platform keys

From the merchant portal: the X25519 body public key with its keyId, and the webhook Ed25519 public keys.

webhookUrl

Receive final payment or payout states at a public HTTPS URL.

Method information

Select paymentMethod or payoutMethod by country and currency.

The SDK is open source, one repository per language. This page is the shortest path to a first order; the SDK Manual covers every method, configuration option and error. See Authentication for the wire protocol it implements.

Install the SDK

Go

go get github.com/deepayment/[email protected]

import deepayment "github.com/deepayment/sdk-go"

Go 1.24 or newer. Package: pkg.go.dev · Source: github.com/deepayment/sdk-go

JavaScript

npm install @support-deepayment/sdk

import { Client } from '@support-deepayment/sdk';

Node.js 18 or newer, ES module. Package: npm · Source: github.com/deepayment/sdk-js

Python

pip install deepayment

from deepayment import Client

Python 3.10 or newer. Package: PyPI · Source: github.com/deepayment/sdk-python

PHP

composer require deepayment/sdk

use Deepayment\Sdk\Client;

PHP 8.2 or newer, with the sodium, json and curl extensions. Package: Packagist · Source: github.com/deepayment/sdk-php

Java

<dependency>
  <groupId>com.deepayment</groupId>
  <artifactId>sdk</artifactId>
  <version>0.1.0</version>
</dependency>

import com.deepayment.sdk.Client;

JDK 17 or newer. Package: Maven Central · Source: github.com/deepayment/sdk-java

Install the Agent Skill

If you write the integration with an AI coding agent, install the skill first. It carries the method codes for each currency, the conditional required fields, and the rules for deciding whether a failed request left an order behind.

npx skills add deepayment/skill

Works with Claude Code, Cursor, Codex and the other agents the skills CLI supports. The agent reads the entry file first and pulls the method tables on demand. Source and manual install instructions: github.com/deepayment/skill. The skill is generated from the same source tree as the SDKs and is updated with them.

Transport Rules

• HTTPS only
• TLS 1.2 or later
• UTF-8 encoding
• JSON request and response bodies; POST bodies are encrypted by the SDK

Production Base URL

https://panama.deepayment.com/api/v1

Integration Flow

1. Generate keys

   Create an Ed25519 key pair. Upload the public key in the merchant portal and copy the Access Key and platform keys. Do not reuse keys across environments.

2. Configure the SDK

   Pass the base URL, Access Key, your private key, the platform body key, and the platform webhook public keys.

3. Create an order

   Pass merchantOrderNo, currency, amount, paymentMethod or payoutMethod, and webhookUrl.

4. Handle the result

   Parse webhooks through the SDK, which verifies the platform signature. Query the order when callbacks are delayed or the create request times out.

Configure the SDK

Replace the placeholder values with the credentials from your merchant portal.

Go

import deepayment "github.com/deepayment/sdk-go"

c, err := deepayment.NewClient(deepayment.Config{
    BaseURL:                     "https://panama.deepayment.com",
    AccessKey:                   "mak_live_xxx",
    MerchantPrivateKeyBase64:    merchantPrivateKey,        // your Ed25519 private key, base64
    PlatformBodyKeyID:           "body_20260827_01",
    PlatformBodyPublicKeyBase64: platformBodyPublicKey,     // platform X25519 public key, base64
    PlatformWebhookPublicKeys: map[string]string{           // keyId -> platform Ed25519 public key, base64
        "pwhk_20260827_01": platformWebhookPublicKey,
    },
})
if err != nil {
    return err
}

JavaScript

const client = new Client({
  baseUrl: 'https://panama.deepayment.com',
  accessKey: 'mak_live_xxx',
  merchantPrivateKeyBase64: merchantPrivateKey,        // your Ed25519 private key, base64
  platformBodyKeyId: 'body_20260827_01',
  platformBodyPublicKeyBase64: platformBodyPublicKey,  // platform X25519 public key, base64
  platformWebhookPublicKeys: {                         // keyId -> platform Ed25519 public key, base64
    pwhk_20260827_01: platformWebhookPublicKey,
  },
});

Python

client = Client(
    base_url="https://panama.deepayment.com",
    access_key="mak_live_xxx",
    merchant_private_key_base64=merchant_private_key,        # your Ed25519 private key, base64
    platform_body_key_id="body_20260827_01",
    platform_body_public_key_base64=platform_body_public_key,  # platform X25519 public key, base64
    platform_webhook_public_keys={                           # keyId -> platform Ed25519 public key, base64
        "pwhk_20260827_01": platform_webhook_public_key,
    },
)

PHP

$client = new Client([
    'baseUrl' => 'https://panama.deepayment.com',
    'accessKey' => 'mak_live_xxx',
    'merchantPrivateKeyBase64' => $merchantPrivateKey,        // your Ed25519 private key, base64
    'platformBodyKeyId' => 'body_20260827_01',
    'platformBodyPublicKeyBase64' => $platformBodyPublicKey,  // platform X25519 public key, base64
    'platformWebhookPublicKeys' => [                          // keyId -> platform Ed25519 public key, base64
        'pwhk_20260827_01' => $platformWebhookPublicKey,
    ],
]);

Java

Client client = Client.builder()
    .baseUrl("https://panama.deepayment.com")
    .accessKey("mak_live_xxx")
    .merchantPrivateKeyBase64(merchantPrivateKey)          // your Ed25519 private key, base64
    .platformBodyKeyId("body_20260827_01")
    .platformBodyPublicKeyBase64(platformBodyPublicKey)    // platform X25519 public key, base64
    .platformWebhookPublicKeys(Map.of(                     // keyId -> platform Ed25519 public key, base64
        "pwhk_20260827_01", platformWebhookPublicKey))
    .build();

Choose an API

Create payment order

The user pays the merchant. Open the Payments directory, then choose country and method.

POST /payments

Create payout order

The merchant sends funds to a user or partner. Open the Payouts directory, then choose country and method.

POST /payouts

Create a Payment

The business fields are the same as the API Reference request body. The SDK encrypts and signs the request for you.

Go

order, err := c.CreatePayment(ctx, &deepayment.CreatePaymentReq{
    MerchantOrderNo: "M202605060001",
    Currency:        "BRL",
    Amount:          "250.00",
    Country:         "BR",
    PaymentMethod: deepayment.PaymentMethod{
        Code: "PIX",
        Pix: &deepayment.PaymentPixExtra{
            PayerCPF:  "12345678901",
            PayerName: "Joao Silva",
        },
    },
    ReturnUrl:  "https://merchant.example/return",
    WebhookUrl: "https://merchant.example/webhook/payment",
    Attach:     "user_123",
})

JavaScript

const order = await client.createPayment({
  merchantOrderNo: 'M202605060001',
  currency: 'BRL',
  amount: '250.00',
  country: 'BR',
  paymentMethod: {
    code: 'PIX',
    pix: { payerCPF: '12345678901', payerName: 'Joao Silva' },
  },
  returnUrl: 'https://merchant.example/return',
  webhookUrl: 'https://merchant.example/webhook/payment',
  attach: 'user_123',
});

Python

order = client.create_payment(CreatePaymentReq(
    merchantOrderNo="M202605060001",
    currency="BRL",
    amount="250.00",
    country="BR",
    paymentMethod={
        "code": "PIX",
        "pix": {"payerCPF": "12345678901", "payerName": "Joao Silva"},
    },
    returnUrl="https://merchant.example/return",
    webhookUrl="https://merchant.example/webhook/payment",
    attach="user_123",
))

PHP

$order = $client->createPayment([
    'merchantOrderNo' => 'M202605060001',
    'currency' => 'BRL',
    'amount' => '250.00',
    'country' => 'BR',
    'paymentMethod' => [
        'code' => 'PIX',
        'pix' => ['payerCPF' => '12345678901', 'payerName' => 'Joao Silva'],
    ],
    'returnUrl' => 'https://merchant.example/return',
    'webhookUrl' => 'https://merchant.example/webhook/payment',
    'attach' => 'user_123',
]);

Java

Map<String, Object> order = client.createPayment(Map.of(
    "merchantOrderNo", "M202605060001",
    "currency", "BRL",
    "amount", "250.00",
    "country", "BR",
    "paymentMethod", Map.of(
        "code", "PIX",
        "pix", Map.of("payerCPF", "12345678901", "payerName", "Joao Silva")),
    "returnUrl", "https://merchant.example/return",
    "webhookUrl", "https://merchant.example/webhook/payment",
    "attach", "user_123"));

Payout creation works the same way with createPayout and a payoutMethod object. See the Payouts directory in API Reference for method fields.

Query an Order

Go

order, err := c.QueryPaymentByMerchantOrderNo(ctx, "M202605060001")

JavaScript

const order = await client.queryPaymentByMerchantOrderNo('M202605060001');

Python

order = client.query_payment_by_merchant_order_no("M202605060001")

PHP

$order = $client->queryPaymentByMerchantOrderNo('M202605060001');

Java

Map<String, Object> order = client.queryPaymentByMerchantOrderNo("M202605060001");

Receive a Webhook

Pass the raw HTTP request to the SDK. It verifies Content-Digest, Webhook-Event-Id, and the platform Ed25519 signature before returning the event. Respond with HTTP 2xx after you have stored the event.

Go

func handlePaymentWebhook(w http.ResponseWriter, r *http.Request) {
    wh, err := c.ParsePaymentWebhook(r)
    if err != nil {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }
    // deduplicate by wh.EventID, then apply wh.Status to order wh.MerchantOrderNo
    w.WriteHeader(http.StatusOK)
}

JavaScript

// Express-style handler with the raw body preserved
const event = await client.parsePaymentWebhook({
  method: req.method,
  path: req.path,
  rawQuery: req.url.split('?')[1] ?? '',
  headers: req.headers,
  body: rawBody, // Buffer or string of the exact bytes received
});
// deduplicate by event.eventId, then apply event.status
res.sendStatus(200);

Python

event = client.parse_payment_webhook(
    method=request.method,
    path=request.path,
    raw_query=request.query_string.decode(),
    headers=dict(request.headers),
    body=request.get_data(),  # exact bytes received
)
# deduplicate by event.eventId, then apply event.status
return "", 200

PHP

$event = $client->parsePaymentWebhook(
    $_SERVER['REQUEST_METHOD'],
    parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH),
    getallheaders(),
    file_get_contents('php://input'),
    $_SERVER['QUERY_STRING'] ?? ''
);
// deduplicate by $event['eventId'], then apply $event['status']
http_response_code(200);

Java

Map<String, Object> event = client.parsePaymentWebhook(
    request.getMethod(),
    request.getRequestURI(),
    headers,          // Map<String, String> of request headers
    rawBody);         // byte[] of the exact bytes received
// deduplicate by event.get("eventId"), then apply event.get("status")
response.setStatus(200);

Response Envelope

All APIs use the same response envelope. The SDK returns the data object and raises an error for any other result. Log traceId for troubleshooting.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "code": 200,
  "msg": "OK",
  "traceId": "7f3d2f0c9b4d4a1a",
  "data": {}
}

Idempotency And Recovery

• Payment and payout creation both use merchantOrderNo as the merchant-side idempotency key.
• Payment and payout order numbers are unique in separate namespaces.
• Repeating the same request with the same merchantOrderNo returns the original order.
• Changing any field and repeating the same merchantOrderNo still returns the original order. The platform does not compare fields, so a changed amount or account silently has no effect. Allocate a new number for a different order.
• The SDK does not retry writes automatically. After timeouts, 5xx, or broken connections, query the order before retrying. A retry is the same create because it reuses the same merchantOrderNo; the idempotency key plays no part.

:::tip Reconciliation webhook is an event notification. Query APIs are the state confirmation surface. Store callbacks idempotently by eventId, then query when events are delayed, duplicated, or out of order. :::