Merchant Onboarding

Transcaty Merchant Onboarding

This guide is for your merchants. Goal: start using Transcaty in a few easy steps.

1) What You Get From Transcaty

When a merchant is onboarded, they get:

  • apiKey
  • secret
  • baseUrl (your API URL)

They use these to call Transcaty APIs.

2) How Payment Flow Works

Merchant talks to Transcaty. Transcaty talks to the payment provider.

So merchant only integrates with Transcaty endpoints.

3) Main Endpoints Merchants Use

Auth / identity

  • GET /v1/me

Balance

  • GET /v1/balance

PAYIN (customer pays merchant)

  • POST /v1/payins
  • GET /v1/payins/:id

PAYOUT (merchant sends money out)

  • POST /v1/payouts
  • GET /v1/payouts/:id

Transactions

  • GET /v1/transactions

4) HMAC Headers (Required for /v1/*)

Merchant must send:

  • X-Transcaty-Key
  • X-Transcaty-Signature
  • X-Transcaty-Timestamp

Signature payload format:

<timestamp>.<raw_json_body>

Hash algorithm:

HMAC-SHA256 with merchant secret.

5) Merchant Webhooks (Available)

Transcaty can notify merchant server after PAYIN/PAYOUT completion.

Configure merchant webhook URL

Use:

  • PATCH /v1/me/webhook

Body example:

{
  "webhookUrl": "https://merchant.com/webhooks/transcaty"
}

Response includes:

  • webhookSecret (save this safely)

Use null to remove webhook:

{
  "webhookUrl": null
}

6) Merchant Webhook Events Sent by Transcaty

Current event types:

  • payin.completed
  • payin.failed
  • payout.completed
  • payout.failed

Headers sent by Transcaty:

  • X-Transcaty-Webhook-Signature (HMAC SHA256)
  • X-Transcaty-Event

Payload shape:

{
  "event": "payin.completed",
  "transactionId": "uuid",
  "status": "success",
  "amount": "500",
  "paidAmount": "500",
  "platformOrderId": "2026031807000000129",
  "timestamp": "2026-03-19T10:00:00.000Z"
}

For failed events, paidAmount may be absent.

7) Important Notes for Merchants

  • Use transactionId from Transcaty as your main reference.
  • platformOrderId is provider-side reference (for support/escalation).
  • Do not call any payment provider directly from merchant integration.
  • If webhook is delayed, poll GET /v1/payins/:id or GET /v1/payouts/:id.

8) Super Quick Test (Merchant)

  1. GET /v1/me
  2. GET /v1/balance
  3. POST /v1/payins
  4. Complete payer step from paymentInfo.content
  5. GET /v1/payins/:id until success
  6. POST /v1/payouts
  7. GET /v1/payouts/:id until final state
  8. Set webhook URL with PATCH /v1/me/webhook and confirm events are received
Overview