PayPlus REST API

API Version: v2.1 Base URL: https://api.payplus.yourbank.internal/v2 Last updated: March 2026

The PayPlus REST API enables your applications to initiate, monitor, and manage payments across all supported US payment rails — ACH, Fedwire, SWIFT, RTP, and FedNow — through a single, unified interface. The API abstracts the complexity of individual rail message formats and handles compliance screening, approval workflow, and network submission on your behalf.

/payments/ach

Initiate ACH credits and debits, submit batch files, retrieve return details, and process reversals

/payments/instant

Initiate real-time credit transfers via RTP (TCH) or FedNow; send Request for Payment (RfP)

/payments/wire

Initiate Fedwire and SWIFT transfers; request payment recall; track settlement status

/webhooks

Subscribe to real-time payment events: approved, settled, returned, compliance hold

Authentication

All API requests require authentication. PayPlus supports two authentication methods:

OAuth 2.0 Client Credentials (Recommended)

For server-to-server API integrations, use OAuth 2.0 Client Credentials grant. Your application authenticates as a PayPlus API Integration User using a client ID and client secret.

Step 1 — Obtain an access token

POST /auth/token

POST /auth/token HTTP/1.1
Host: api.payplus.yourbank.internal
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=your_client_id
&client_secret=your_client_secret
&scope=payments:write payments:read

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "payments:write payments:read"
}

Step 2 — Include the token in API requests

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Access tokens expire after 3600 seconds (1 hour). Implement token refresh logic in your integration — do not cache tokens indefinitely.

API Key Authentication

For simpler integrations or test environments, API key authentication is available. Generate API keys in the PayPlus Admin Console at Administration > API > API Keys.

X-API-Key: pp_live_a3k9f2m8x7p...

API Key Security Never expose API keys in client-side code (JavaScript, mobile apps). API keys should only be used in server-side code where they cannot be extracted by end users. For all production integrations handling real payments, OAuth 2.0 is strongly recommended over API key authentication.

Available Scopes

Scope	Description
`payments:write`	Initiate payments across all rails. Required for POST endpoints.
`payments:read`	Retrieve payment status, history, and details. Required for GET endpoints.
`payments:ach`	ACH-specific access. Include in addition to `payments:write`/`payments:read` to restrict a client to ACH only.
`payments:instant`	Instant payment (RTP/FedNow) specific access.
`payments:wire`	Wire transfer (Fedwire/SWIFT) specific access.
`webhooks:manage`	Create, update, and delete webhook subscriptions.

Requests and Responses

Request Format

All request and response bodies are JSON (Content-Type: application/json).
All timestamps are ISO 8601 / RFC 3339 format in UTC: 2026-03-15T14:30:00Z
All monetary amounts are integers in cents (USD). Example: $1,250.00 = 125000. This avoids floating-point precision issues.
ABA routing numbers, account numbers, and BIC codes are strings to preserve leading zeros.

Response Envelope

All successful responses return an object with a data field containing the resource. Error responses use the error field instead.

// Success response
{
  "data": {
    "paymentId": "pmt_a3k9f2m8x7p4r1q0",
    "status": "submitted",
    ...
  },
  "meta": {
    "requestId": "req_7f3b2d1a9e4c",
    "timestamp": "2026-03-15T14:30:05Z"
  }
}

// Error response
{
  "error": {
    "code": "INVALID_ROUTING_NUMBER",
    "message": "The provided routing number '099999999' is not valid.",
    "field": "beneficiary.routingNumber"
  },
  "meta": {
    "requestId": "req_7f3b2d1a9e4c",
    "timestamp": "2026-03-15T14:30:05Z"
  }
}

Idempotency

All payment initiation endpoints (POST) support idempotency keys. Include the Idempotency-Key header with a unique value (UUID v4) to safely retry failed requests without risk of creating duplicate payments.

Idempotency-Key: a3b9f2d1-4e7c-8f0a-b3d5-1e9c7a2f4b08

If a request with the same idempotency key is received within 24 hours, PayPlus returns the original response without creating a new payment. Idempotency keys expire after 24 hours.

Environments

Environment	Base URL	Notes
Production	`https://api.payplus.yourbank.internal/v2`	Processes real payments. Requires production credentials. Access restricted to authorized application servers.
UAT / Staging	`https://api-uat.payplus.yourbank.internal/v2`	Connected to FedACH test environment, TCH RTP certification environment, and Fedwire test environment. Uses test credentials — no real money moves.
Sandbox	`https://api-sandbox.payplus.yourbank.internal/v2`	Fully simulated environment. No connection to payment networks. Instant responses for all payment types. Ideal for rapid integration development.

Rate Limiting

Limit	Value	Scope
Default request rate	120 requests per minute	Per API client (client_id)
Burst allowance	Up to 200 requests per minute for up to 30 seconds	Per API client
Payment initiation	60 POST requests per minute	Per API client (sub-limit of default)

Rate limit status is returned in response headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1742039460    // Unix timestamp when limit resets

When the rate limit is exceeded, the API returns 429 Too Many Requests. Implement exponential backoff in your retry logic.

API Versioning

The API version is included in the URL path (/v2/). Breaking changes are introduced in new major versions. Minor versions (v2.1, v2.2) add new fields and endpoints without removing or changing existing ones — existing integrations continue to work without modification.

The current version is v2.1. Version v1 is deprecated and will be retired on December 31, 2026. Migrate v1 integrations to v2 before that date.