Payment Execution API

Submit cross-border payment instructions, track settlement status, and manage partner integrations.

Multi-Channel Payment Submission

The Payment Execution API supports multiple submission channels to accommodate different bank and PSP integration requirements:

🔌

API (REST)

🌐

SWIFT

📁

SFTP

📧

POST/api/v1/payments/instructions

Submit a new payment instruction for execution via the selected settlement route and channel.

Request Body

{
  "amount": 50000.00,
  "currency": "USD",
  "beneficiary": {
    "name": "Acme Corp Ltd",
    "country": "GB",
    "bankAccount": {
      "accountNumber": "12345678",
      "bankName": "Barclays Bank",
      "swiftBic": "BARCGB22",
      "country": "GB"
    },
    "address": {
      "street": "123 Business Park",
      "city": "London",
      "postalCode": "EC1A 1BB",
      "country": "GB"
    }
  },
  "purpose": {
    "code": "trade_settlement",
    "description": "Invoice INV-2025-0001 for electronics shipment"
  },
  "settlementRoute": {
    "routeId": "route_ng_gb_swift",
    "partnerPreference": "wise",
    "channelPreference": "api",
    "settlementTimeline": "t_plus_2"
  },
  "valueDate": "2026-01-10",
  "clientReference": "PAY-XYZ123"
}

Request Parameters

Field	Type	Required	Description
amount	number	Yes	Payment amount in the specified currency
currency	string	Yes	ISO 4217 currency code (USD, EUR, GBP, etc.)
beneficiary	object	Yes	Beneficiary details including bank account
purpose.code	string	Yes	Payment purpose: trade_settlement, service_payment, etc.
settlementRoute	object	Yes	Route and channel preferences
valueDate	string	No	Requested settlement date (ISO 8601)
clientReference	string	No	Your unique reference for this payment

Response

{
  "success": true,
  "data": {
    "instructionId": "instr_abc123def456",
    "status": "submitted",
    "clientReference": "PAY-XYZ123",
    "submittedAt": "2026-01-08T10:30:00Z",
    "settlementDetails": {
      "expectedSettlementDate": "2026-01-10",
      "settlementTimeline": "t_plus_2",
      "partnerName": "Wise Business",
      "channel": "api"
    },
    "fees": {
      "estimated": 25.00,
      "currency": "USD"
    }
  }
}

GET/api/v1/payments/instructions/:instructionId

Retrieve the current status and details of a payment instruction.

Path Parameters

Parameter	Type	Description
instructionId	string	Unique payment instruction identifier

Response

{
  "success": true,
  "data": {
    "instructionId": "instr_abc123def456",
    "status": "processing",
    "clientReference": "PAY-XYZ123",
    "amount": 50000.00,
    "currency": "USD",
    "submittedAt": "2026-01-08T10:30:00Z",
    "lastUpdatedAt": "2026-01-08T14:15:00Z",
    "settlementDetails": {
      "expectedSettlementDate": "2026-01-10",
      "settlementTimeline": "t_plus_2",
      "partnerReference": "WISE-REF-789"
    },
    "statusHistory": [
      {
        "status": "submitted",
        "timestamp": "2026-01-08T10:30:00Z"
      },
      {
        "status": "accepted",
        "timestamp": "2026-01-08T10:31:00Z",
        "message": "Payment accepted by Wise"
      },
      {
        "status": "processing",
        "timestamp": "2026-01-08T14:15:00Z",
        "message": "Payment is being processed"
      }
    ]
  }
}

PUT/api/v1/payments/instructions/:instructionId/status

Settlement partners use this endpoint to report status changes. Requires partner authentication.

Request Body

{
  "status": "processing",
  "partnerReference": "SWIFT-REF-123",
  "timestamp": "2026-01-08T11:00:00Z",
  "details": {
    "message": "Payment accepted by correspondent bank",
    "bankReference": "CORR-456"
  }
}

Status Values

Status	Description
pending	Instruction received, awaiting submission
submitted	Submitted to settlement partner
accepted	Accepted by settlement partner
processing	Being processed by banking network
settled	Settlement confirmed
failed	Payment failed
cancelled	Cancelled before settlement
returned	Funds returned after settlement

POST/api/v1/payments/instructions/:instructionId/settlement

Partners confirm final settlement of the payment with actual amounts and fees.

Request Body

{
  "confirmedAt": "2026-01-10T14:30:00Z",
  "settlementReference": "SETTLE-XYZ789",
  "actualAmount": 50000.00,
  "actualCurrency": "USD",
  "beneficiaryReceived": {
    "amount": 41250.00,
    "currency": "GBP"
  },
  "exchangeRate": {
    "rate": 0.825,
    "timestamp": "2026-01-10T14:30:00Z"
  },
  "fees": {
    "amount": 25.00,
    "currency": "USD",
    "breakdown": [
      { "type": "transfer_fee", "amount": 15.00 },
      { "type": "swift_fee", "amount": 10.00 }
    ]
  }
}

GET/api/v1/payments/track

Track multiple payments in a single request. Useful for dashboard displays and batch monitoring.

Query Parameters

Parameter	Type	Description
instructionIds	string	Comma-separated list of instruction IDs (max 50)
status	string	Filter by status (optional)
fromDate	string	Filter by submission date (optional)

Response

{
  "success": true,
  "data": {
    "instructions": [
      {
        "instructionId": "instr_abc123",
        "status": "settled",
        "amount": 50000.00,
        "currency": "USD",
        "settlementDetails": {
          "settledAt": "2026-01-10T14:30:00Z"
        }
      },
      {
        "instructionId": "instr_def456",
        "status": "processing",
        "amount": 25000.00,
        "currency": "EUR",
        "settlementDetails": {
          "expectedSettlementDate": "2026-01-11"
        }
      }
    ],
    "summary": {
      "total": 2,
      "byStatus": {
        "settled": 1,
        "processing": 1
      }
    }
  }
}

Settlement Timelines

Timeline	Description	Typical Use
instant	Real-time settlement	P2P transfers, urgent payments
same_day	Same business day	Urgent trade settlements
t_plus_1	Next business day	Standard urgent payments
t_plus_2	Two business days	Standard trade settlements
t_plus_n	Custom timeline	Special arrangements

Webhook Notifications

Heydeo sends webhook notifications to your registered endpoint for important status changes. All webhooks are signed using HMAC-SHA256 for verification.

Webhook Events

Event	Description
payment.submitted	Instruction submitted to partner
payment.accepted	Partner accepted the instruction
payment.processing	Payment is being processed
payment.settled	Settlement confirmed
payment.failed	Payment failed
payment.returned	Funds returned after settlement

Webhook Payload

{
  "event": "payment.status_changed",
  "timestamp": "2026-01-08T11:00:00Z",
  "data": {
    "instructionId": "instr_abc123",
    "status": "processing",
    "previousStatus": "accepted",
    "clientReference": "PAY-XYZ123"
  },
  "signature": "sha256=a1b2c3d4e5f6..."
}

Signature Verification

import { createHmac } from 'crypto'

function verifyWebhook(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = `sha256=${
    createHmac('sha256', secret)
      .update(payload)
      .digest('hex')
  }`
  return signature === expected
}

Error Codes

Code	HTTP	Description
INVALID_REQUEST	400	Request validation failed
UNAUTHORIZED	401	Authentication required
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Payment instruction not found
DUPLICATE	409	Duplicate instruction (idempotency)
COMPLIANCE_BLOCK	422	Blocked by compliance rules
RATE_LIMIT	429	Too many requests

📊 Rate Limits

POST /payments/instructions:: 100 requests/min
GET /payments/instructions/*:: 300 requests/min
PUT /*/status (partner):: 500 requests/min
GET /payments/track:: 60 requests/min