Home / API Guide

API guide and full API reference

REST API v1 | Developer integration manual

Secure transaction orchestration for buyers, sellers, brokers, funding, delivery, approvals and controlled fund release.

Base URL

https://api.rbcpay.com/v1

API version

Format

REST over HTTPS, JSON requests and responses

Authentication

OAuth 2.0 bearer access tokens

Developer quick reference

Need	Endpoint or action
Authenticate	POST /oauth/token
Create transaction	POST /transactions
Read transaction	GET /transactions/{id}
Submit for acceptance	POST /transactions/{id}/submit
Accept terms	POST /transactions/{id}/accept
Create funding	POST /transactions/{id}/funding-intents
Check funding	GET /transactions/{id}/funding
Report fulfilment	POST /transactions/{id}/fulfilments
Confirm receipt	POST /transactions/{id}/confirm-receipt
Release funds	POST /transactions/{id}/release
Refund	POST /transactions/{id}/refunds
Open dispute	POST /transactions/{id}/disputes
Upload evidence	POST /files
Register webhook	POST /webhook-endpoints
Reconcile events	GET /events

Full API reference

Document control
1. Platform overview
2. Environments and base URLs
3. Authentication and authorization
4. Security requirements
5. Request conventions
6. Idempotency and retries
7. Pagination, filtering and expansion
8. Transaction lifecycle and state machine
9. Core resource models
10. API reference – authentication
11. API reference – transactions
12. API reference – parties and acceptance
13. API reference – funding
14. API reference – fulfilment and delivery
15. API reference – release and payout
16. API reference – refunds and cancellations
17. API reference – disputes
18. API reference – brokers and commissions
19. API reference – files and evidence
20. API reference – webhooks
21. API reference – events and audit trail
22. API reference – health and metadata
23. Error model
24. Rate limits
25. Webhook security and replay protection
26. Integration recipes
27. SDK patterns and code examples
28. Sandbox and test scenarios
29. Production readiness checklist
30. Data protection and operational security
31. Versioning and deprecation
32. Glossary
Appendix A. Status codes
Appendix B. Event catalogue
Appendix C. Example end-to-end transaction
Appendix D. Source and implementation notes
Developer quick reference

RBC PAY / DEVELOPER DOCUMENTATION

RBC PAY

API GUIDE & FULL API REFERENCE

REST API v1 | Developer Integration Manual

Secure transaction orchestration for buyers, sellers, brokers, funding, delivery, approvals and controlled fund release.

Publication note This manual expands the public RBC Pay API Guide into a complete v1 integration specification. The public guide confirms the core REST/OAuth/JSON architecture and transaction lifecycle. Resource fields and endpoints not yet described publicly are specified here as the v1 implementation contract and should be validated against the deployed backend before public launch.

Version 1.0 | August 26, 2026

https://api.rbcpay.com/v1

Document control

Item	Value
Document	RBC Pay API Guide & Full API Reference
Version	1.0
API version	v1
Base URL	https://api.rbcpay.com/v1
Format	REST over HTTPS; JSON requests and responses
Authentication	OAuth 2.0 bearer access tokens
Intended readers	Backend engineers, platform architects, security teams, QA, integration partners, brokers and technical operations
Status	Developer reference specification; confirm implementation-specific limits and production availability before release

Conventions used in this guide

All timestamps use ISO 8601 / RFC 3339 in UTC, for example 2026-08-26T18:42:31Z.

All monetary amounts use decimal strings in request/response examples where precision matters. Do not use binary floating-point for accounting logic.

Resource identifiers are opaque strings such as txn_01J…, pty_01J…, wh_01J…. Do not infer business meaning from IDs.

Fields marked required are required by this reference contract unless the endpoint says otherwise.

Sensitive credentials belong on trusted server-side systems only.

1. Platform overview

RBC Pay provides a transaction API for coordinating commercial transactions between buyers, sellers and, when applicable, brokers. The API is designed around explicit transaction terms, party acceptance, confirmed funding, fulfilment, receipt or approval, controlled fund release, commission allocation and an auditable event history.

The public RBC Pay API Guide describes a practical lifecycle: create the transaction, fund it, complete approvals, deliver or fulfil, release funds, and pay the participants. It also identifies OAuth 2.0, HTTPS/JSON REST endpoints, webhooks, sandbox testing, IP allowlisting and server-side credential handling as core integration concepts.

1.1 Design principles

Server-to-server by default: secret credentials never ship in browser or mobile application code.

State-driven workflow: integrations act on authoritative transaction status rather than guessing from UI state.

Explicit approval: acceptance and release actions are represented as API operations with timestamps and actors.

Idempotent money movement: creation, funding, release, refund and dispute actions are protected from duplicate submission.

Webhook-first synchronization: applications receive events and reconcile them against the API.

Auditability: material state changes produce immutable events suitable for operational review.

1.2 High-level architecture

Client Backend  --->  RBC Pay API  --->  Transaction Ledger / Risk / Payment Rails
      |                    |
      |<--- Webhooks -------|
      |
      +-- Your database, order system, CRM, notifications and reconciliation jobs

2. Environments and base URLs

Environment	Base URL	Purpose
Production	https://api.rbcpay.com/v1	Live transactions and production credentials.
Sandbox	Provisioned through the RBC Pay developer environment	Safe integration testing using non-production credentials and test scenarios.

Environment isolation Treat sandbox and production as completely separate security domains. Never reuse secrets, webhook signing secrets, idempotency keys or stored test data across environments.

2.1 Transport requirements

HTTPS only. Reject plaintext HTTP and never follow a downgrade redirect for API requests.

Use TLS 1.2 or later; TLS 1.3 is preferred where supported.

Send UTF-8 JSON with Content-Type: application/json unless uploading a file.

Set a descriptive User-Agent, for example MyPlatform/2.4 rbcpay-integration/1.0.

3. Authentication and authorization

RBC Pay uses OAuth 2.0 bearer access tokens. Every authenticated API request includes the access token in the Authorization header. Credentials and tokens must remain on trusted server-side systems.

Authorization: Bearer {access_token}

3.1 Recommended OAuth flow

For machine-to-machine integrations, use the OAuth 2.0 client credentials grant. A partner exchanges its client ID and client secret for a short-lived access token and requests only the scopes required by that integration.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=transactions:read transactions:write webhooks:manage

3.2 Scopes

Scope	Allows
transactions:read	Read transactions, statuses, terms and related event metadata.
transactions:write	Create and modify permitted transaction terms and workflow actions.
parties:read	Read party participation and acceptance status.
parties:write	Invite or manage permitted transaction participants.
funding:read	Read funding instructions and confirmed funding state.
funding:write	Create permitted funding intents or confirm authorized funding workflow actions.
payouts:read	Read release and payout status.
payouts:write	Initiate permitted release operations.
refunds:write	Create refunds where allowed.
disputes:read	Read dispute cases and evidence requirements.
disputes:write	Open disputes and submit dispute evidence.
files:write	Upload files/evidence to a transaction or dispute.
events:read	Read immutable API event history.
webhooks:manage	Create, rotate, disable and inspect webhook endpoints.

3.3 Token handling

Cache access tokens only for their valid lifetime and refresh by obtaining a new token, not by extending local expiry.

Never log client secrets, bearer tokens, webhook secrets, bank credentials or full identity documents.

Rotate client secrets routinely and immediately after suspected exposure.

Use separate credentials per production service or integration where operationally possible.

4. Security requirements

4.1 IP allowlisting

Production credentials can be restricted to approved source IP ranges. Design integrations so outbound API traffic originates from stable, documented egress addresses.

4.2 Secret storage

Store secrets in a managed secrets service, HSM-backed key store or equivalent protected environment variable injection system.

Apply least privilege to people and workloads that can read production credentials.

Do not put API credentials in source control, container images, ticketing systems, screenshots or client-side JavaScript.

4.3 Sensitive data minimization

Send only data required to establish the transaction, perform compliance checks, reconcile payment state or resolve a dispute. Avoid placing unnecessary personal or financial information in free-text fields.

4.4 Logging

Log request IDs, resource IDs, endpoint paths, response status, latency and internal correlation IDs. Redact Authorization headers, secrets, payment credentials, identity documents and private evidence URLs.

5. Request conventions

5.1 Common request headers

Header	Required	Description
Authorization	Yes	Bearer access token.
Content-Type	For JSON writes	application/json.
Accept	Recommended	application/json.
Idempotency-Key	Money/creation writes	Unique key for safely retrying a write.
X-Request-ID	Recommended	Client-generated trace identifier. Use a UUID or equivalent unique value.
User-Agent	Recommended	Identifies your integration and version.

5.2 Common response headers

Header	Meaning
X-Request-ID	RBC Pay request identifier used for support and tracing.
RateLimit-Limit	Maximum requests in the current policy window, when supplied.
RateLimit-Remaining	Requests remaining in the policy window, when supplied.
RateLimit-Reset	Time or offset until the limit resets, when supplied.
Retry-After	Seconds to wait after 429 or certain transient failures.

5.3 Monetary fields

Represent money as a decimal string plus an ISO 4217 currency code. Example: {“amount”:”12500.00″,”currency”:”CAD”}. Your ledger must use decimal or integer minor-unit arithmetic, never binary floating-point arithmetic.

5.4 Dates and timestamps

Use UTC timestamps in RFC 3339. Date-only contractual deadlines use YYYY-MM-DD and must be interpreted according to the transaction agreement and jurisdiction.

6. Idempotency and retries

Any request that can create a duplicate financial or contractual effect must be idempotent. Send an Idempotency-Key that is unique to the logical operation, not merely to the HTTP attempt.

Idempotency-Key: 6f6ab41d-4d15-47a6-b893-963dd870a8e8

Reuse the same key when retrying the exact same logical request after a timeout or transient 5xx failure.

Use a new key when the intended operation or request body changes.

Store the key and resulting RBC Pay resource ID in your own database for reconciliation.

Do not automatically retry 4xx validation, authorization or business-rule failures unless the underlying cause is corrected.

6.1 Retry policy

Use exponential backoff with jitter for 429 and retryable 5xx responses. Honor Retry-After when present. Cap retries and move persistent failures into an operational queue for review.

7. Pagination, filtering and expansion

7.1 Cursor pagination

GET /transactions?limit=50&starting_after=txn_01J...

{
  "object": "list",
  "data": [...],
  "has_more": true,
  "next_cursor": "txn_01J..."
}

7.2 Common filters

Query	Example	Purpose
status	funded	Filter by resource status.
created_from	2026-08-01T00:00:00Z	Lower time bound.
created_to	2026-08-31T23:59:59Z	Upper time bound.
buyer_email	buyer@example.com	Operational lookup where permitted.
external_reference	ORDER-94821	Correlate to your system.
limit	50	Page size; server-enforced max applies.

8. Transaction lifecycle and state machine

The transaction is the primary orchestration object. Its status represents the latest authoritative workflow state. An integration must not release goods, acknowledge payment, or mark an order completed based solely on a client-side screen or email; confirm state through the API and/or a verified webhook.

Status	Meaning	Typical next actions
draft	Terms are being assembled.	Update terms, add parties, submit for acceptance.
pending_acceptance	Waiting for one or more required parties.	Party accepts or rejects.
accepted	Required parties accepted the current terms.	Create/complete funding.
funding_pending	Funding initiated but not confirmed.	Wait for funding event; reconcile.
funded	Required funds confirmed as received/secured.	Seller fulfils; add shipping/delivery evidence.
in_fulfilment	Goods/services are being delivered.	Update fulfilment; buyer reviews.
delivered	Delivery or fulfilment reported.	Buyer confirms receipt/approval; inspection window runs.
release_pending	Release was requested and is processing.	Wait for payout state.
released	Authorized funds released to seller/beneficiaries.	Reconcile payout/commission.
partially_refunded	Part of the transaction was refunded.	Continue or close per agreement.
refunded	Funds returned according to refund action.	Close/reconcile.
disputed	A dispute prevents normal release.	Submit evidence; await resolution.
cancelled	Transaction terminated before final release.	Reconcile any return of funds.
closed	No further ordinary workflow action is expected.	Retain records and audit history.

8.1 State-change rules

Material term changes after acceptance invalidate the relevant acceptance and return the transaction to pending_acceptance unless the change is explicitly classified as non-material.

Funding confirmation is authoritative only when status becomes funded or the funding resource shows confirmed/succeeded.

Release is permitted only when required contractual conditions are satisfied or an authorized dispute/administrative decision permits release.

A dispute can place a hold on release until resolution.

9. Core resource models

9.1 Transaction object

Field	Type	Description
id	string	Opaque transaction ID.
object	string	“transaction”.
status	enum	Current transaction status.
title	string	Human-readable transaction title.
description	string│null	Optional summary.
amount	decimal string	Gross transaction amount.
currency	string	ISO 4217 code, e.g. CAD.
external_reference	string│null	Your order/deal/reference ID.
buyer	party summary	Buyer participant.
seller	party summary	Seller participant.
brokers	array	Broker participants and commission data.
items	array	Goods/services covered by the terms.
terms	object	Acceptance, inspection, release and special terms.
funding	object│null	Latest funding summary.
fulfilment	object│null	Latest fulfilment summary.
release	object│null	Latest release/payout summary.
metadata	object	Your non-sensitive key/value metadata.
created_at	timestamp	Creation time.
updated_at	timestamp	Last modification time.
livemode	boolean	True in production, false in sandbox.

9.2 Item object

Field	Type	Required	Description
name	string	Yes	Item/service name.
description	string	No	Contractual description.
quantity	integer	Yes	Positive quantity.
unit_price	decimal string	No	Per-unit price where applicable.
sku	string	No	Seller or buyer SKU.
serial_numbers	array	No	Serial/asset identifiers.
condition	enum	No	new, used, refurbished, service, other.
metadata	object	No	Non-sensitive internal mapping data.

9.3 Terms object

Field	Type	Description
inspection_period_hours	integer	Time allowed for buyer review after delivery where applicable.
release_policy	enum	buyer_confirmation, milestone, scheduled, administrative, or contract_specific.
auto_release_at	timestamp│null	Automatic release time when contractually permitted.
shipping_required	boolean	Whether fulfilment requires shipping/tracking.
allowed_carriers	array│null	Optional permitted carrier codes/names.
delivery_deadline	timestamp│null	Contractual fulfilment deadline.
special_terms	string│null	Plain-language terms; avoid secrets or unnecessary personal data.
acceptance_version	integer	Incremented when material terms change.

9.4 Party object

Field	Type	Description
id	string	Opaque party/participation ID.
role	enum	buyer, seller, broker, agent.
email	string	Email used for invitation/identity linkage.
display_name	string│null	Business or person display name.
organization	string│null	Organization name.
acceptance_status	enum	pending, accepted, rejected, revoked, superseded.
accepted_at	timestamp│null	Acceptance timestamp.
verification_status	enum	unverified, pending, verified, restricted, failed.

10. API reference - authentication

POST /oauth/token

Create access token

Exchange OAuth client credentials for a short-lived bearer access token.

Property	Requirement
Authentication	HTTP Basic or client credentials in request body, according to issued credential profile
Idempotency	Not required

Request body

Field	Type	Required	Description
grant_type	string	Yes	client_credentials.
client_id	string	Yes*	Client identifier if not supplied by HTTP Basic.
client_secret	string	Yes*	Client secret if not supplied by HTTP Basic.
scope	string	No	Space-delimited requested scopes.

Example request

curl -X POST https://api.rbcpay.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$RBCPAY_CLIENT_ID&client_secret=$RBCPAY_CLIENT_SECRET&scope=transactions:read%20transactions:write"

Example response

{"access_token":"rbp_at_...","token_type":"Bearer","expires_in":3600,"scope":"transactions:read transactions:write"}

Endpoint-specific errors

Code	HTTP	Meaning
invalid_client	401	Client credentials are invalid or disabled.
invalid_scope	400	Requested scope is not permitted.
unsupported_grant_type	400	Grant type is not supported.

11. API reference - transactions

POST /transactions

Create transaction

Create a transaction with parties, amount, items and contractual terms. The public guide demonstrates POST /transactions and identifies parties, amount, currency, items and broker commission as transaction inputs.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	transactions:write

Request body

Field	Type	Required	Description
title	string	Yes	Transaction title.
description	string	No	Transaction description.
amount	decimal string	Yes	Gross amount.
currency	string	Yes	ISO 4217 currency.
buyer	object	Yes	Buyer invitation/details.
seller	object	Yes	Seller invitation/details.
items	array	Yes	One or more transaction items.
commission	decimal string/object	No	Broker commission where applicable.
terms	object	Yes	Inspection, fulfilment and release conditions.
external_reference	string	No	Your order/deal ID.
metadata	object	No	Non-sensitive integration metadata.

Example request

curl -X POST https://api.rbcpay.com/v1/transactions \
  -H "Authorization: Bearer $RBCPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0c2c9d9d-672b-4ed2-97fa-4d856523ca61" \
  -d '{
    "title":"Server equipment purchase",
    "amount":"12500.00",
    "currency":"CAD",
    "external_reference":"PO-44718",
    "buyer":{"email":"buyer@example.com"},
    "seller":{"email":"seller@example.com"},
    "items":[{"name":"Server equipment","quantity":1}],
    "terms":{"inspection_period_hours":48,"release_policy":"buyer_confirmation"}
  }'

Example response

{
  "id":"txn_01J6C2A9T4...",
  "object":"transaction",
  "status":"pending_acceptance",
  "amount":"12500.00",
  "currency":"CAD",
  "external_reference":"PO-44718",
  "created_at":"2026-08-26T18:42:31Z",
  "livemode":false
}

Endpoint-specific errors

Code	HTTP	Meaning
invalid_currency	422	Currency is not supported for the transaction.
invalid_amount	422	Amount fails format or transaction limits.
party_conflict	409	Participant configuration is not permitted.
duplicate_reference	409	External reference uniqueness rule was violated, if configured.

GET /transactions/{transaction_id}

Retrieve transaction

Return the authoritative representation of a transaction.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	transactions:read

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.
expand	query	string	No	Comma-separated related objects, e.g. events,parties,funding.

Example response

{ "id":"txn_01J6C2A9T4...", "object":"transaction", "status":"funded", "amount":"12500.00", "currency":"CAD", "buyer":{...}, "seller":{...}, "funding":{"status":"confirmed"}, "updated_at":"2026-08-27T10:15:00Z" }

Endpoint-specific errors

Code	HTTP	Meaning
not_found	404	Transaction does not exist or is not visible to these credentials.

GET /transactions

List transactions

List transactions visible to the authenticated integration using cursor pagination.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	transactions:read

Parameters

Name	In	Type	Required	Description
limit	query	integer	No	Page size.
starting_after	query	string	No	Cursor from previous response.
status	query	enum	No	Filter by status.
external_reference	query	string	No	Filter by your reference.
created_from	query	timestamp	No	Created on/after.
created_to	query	timestamp	No	Created before/on.

Example response

{ "object":"list", "data":[{"id":"txn_...","status":"funded"}], "has_more":false, "next_cursor":null }

PATCH /transactions/{transaction_id}

Update transaction

Update mutable transaction fields. Material changes to accepted terms increment acceptance_version and can require parties to re-accept.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	transactions:write

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Request body

Field	Type	Required	Description
title	string	No	Updated title.
description	string	No	Updated description.
items	array	No	Updated items if state permits.
terms	object	No	Updated terms if state permits.
metadata	object	No	Metadata merge/replace per implementation.

Endpoint-specific errors

Code	HTTP	Meaning
invalid_state	409	Transaction cannot be edited in its current state.
reacceptance_required	409	The attempted workflow action requires new acceptance first.

POST /transactions/{transaction_id}/submit

Submit for acceptance

Freeze the current material terms version and invite required parties to accept.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	transactions:write

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Example response

{ "id":"txn_...", "status":"pending_acceptance", "terms":{"acceptance_version":3} }

Endpoint-specific errors

Code	HTTP	Meaning
incomplete_terms	422	Required parties/items/terms are missing.
invalid_state	409	Transaction is not submit-ready.

POST /transactions/{transaction_id}/cancel

Cancel transaction

Request cancellation when the current state and contract permit it. Funded transactions may require refund/return logic rather than immediate cancellation.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	transactions:write

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Request body

Field	Type	Required	Description
reason	string	Yes	Structured or approved cancellation reason.
note	string	No	Non-sensitive operational note.

Example response

{ "id":"txn_...", "status":"cancelled", "cancelled_at":"2026-08-28T12:00:00Z" }

Endpoint-specific errors

Code	HTTP	Meaning
invalid_state	409	Cancellation is not permitted in the current state.
funds_action_required	409	Funds must be refunded or resolved before cancellation can complete.

12. API reference - parties and acceptance

GET /transactions/{transaction_id}/parties

List transaction parties

Return buyer, seller, broker and other authorized participants.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	parties:read

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

POST /transactions/{transaction_id}/parties

Add party

Add an invited participant before the workflow state prevents party changes.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	parties:write

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Request body

Field	Type	Required	Description
role	enum	Yes	buyer, seller, broker or authorized role.
email	string	Yes	Participant email.
display_name	string	No	Display name.
organization	string	No	Company/organization.
permissions	array	No	Role-specific permissions where enabled.

Endpoint-specific errors

Code	HTTP	Meaning
invalid_state	409	Parties are locked in the current state.
duplicate_party	409	Participant already exists in this role.

POST /transactions/{transaction_id}/accept

Accept terms

Record acceptance of the current acceptance_version by the authenticated/authorized participant or delegated acceptance flow.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	transactions:write

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Request body

Field	Type	Required	Description
acceptance_version	integer	Yes	Exact version being accepted.
actor_reference	string	No	Integration-side actor/audit reference.
ip_context	object	No	Only where lawfully collected and permitted.

Example response

{ "transaction_id":"txn_...", "acceptance_version":3, "status":"accepted", "accepted_at":"2026-08-26T19:02:00Z" }

Endpoint-specific errors

Code	HTTP	Meaning
version_mismatch	409	Terms changed; retrieve and accept current version.
not_authorized_party	403	Actor cannot accept for this role.

POST /transactions/{transaction_id}/reject

Reject terms

Record rejection of the current transaction terms.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	transactions:write

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Request body

Field	Type	Required	Description
acceptance_version	integer	Yes	Version being rejected.
reason	string	No	Reason for rejection.

13. API reference - funding

Funding endpoints create and track the buyer-side funding workflow. They do not mean funds are secured until the funding resource is confirmed and the transaction reaches the funded state.

POST /transactions/{transaction_id}/funding-intents

Create funding intent

Create the funding instruction/intent for an accepted transaction.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	funding:write

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Request body

Field	Type	Required	Description
amount	decimal string	Yes	Amount to fund; normally transaction required amount.
currency	string	Yes	Currency matching the transaction.
method	enum	No	bank_transfer, wire, supported_method or auto.
return_url	url	No	Return URL for supported interactive flows.
metadata	object	No	Non-sensitive reconciliation metadata.

Example response

{ "id":"fnd_01J...", "object":"funding_intent", "status":"pending", "amount":"12500.00", "currency":"CAD", "instructions":{"reference":"RBP-7Q29X"} }

Endpoint-specific errors

Code	HTTP	Meaning
transaction_not_accepted	409	Required acceptance is incomplete.
currency_mismatch	422	Funding currency does not match transaction.
invalid_state	409	Transaction cannot be funded in current state.

GET /transactions/{transaction_id}/funding

Retrieve funding status

Return funding objects and confirmed amount for a transaction.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	funding:read

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Example response

{ "transaction_id":"txn_...", "required_amount":"12500.00", "confirmed_amount":"12500.00", "currency":"CAD", "status":"confirmed", "confirmed_at":"2026-08-27T10:15:00Z" }

GET /funding-intents/{funding_intent_id}

Retrieve funding intent

Read one funding intent and its processing status.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	funding:read

Parameters

Name	In	Type	Required	Description
funding_intent_id	path	string	Yes	Funding intent ID.

14. API reference - fulfilment and delivery

POST /transactions/{transaction_id}/fulfilments

Create fulfilment

Report shipment, service delivery or another fulfilment action after funds are confirmed and the transaction permits fulfilment.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	transactions:write

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Request body

Field	Type	Required	Description
type	enum	Yes	shipment, service, digital, pickup, other.
carrier	string	No	Carrier code/name.
tracking_number	string	No	Tracking number.
shipped_at	timestamp	No	Shipment time.
estimated_delivery_at	timestamp	No	Estimated delivery.
items	array	No	Specific items/quantities fulfilled.
evidence_file_ids	array	No	Supporting uploaded evidence.

Example response

{ "id":"ful_01J...", "status":"in_transit", "carrier":"DHL", "tracking_number":"1234567890" }

Endpoint-specific errors

Code	HTTP	Meaning
not_funded	409	Transaction is not confirmed funded.
invalid_carrier	422	Carrier is not permitted under the terms.
invalid_state	409	Fulfilment cannot be created in current state.

PATCH /fulfilments/{fulfilment_id}

Update fulfilment

Update tracking or delivery information.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	transactions:write

Parameters

Name	In	Type	Required	Description
fulfilment_id	path	string	Yes	Fulfilment ID.

Request body

Field	Type	Required	Description
tracking_number	string	No	Updated tracking.
status	enum	No	in_transit, delivered, failed, returned, completed.
delivered_at	timestamp	No	Delivery timestamp.
evidence_file_ids	array	No	Additional evidence.

POST /transactions/{transaction_id}/confirm-receipt

Buyer confirms receipt

Record buyer receipt/approval where required by the release policy.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	transactions:write

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Request body

Field	Type	Required	Description
confirmation	enum	Yes	received_and_accepted or received_with_issue.
note	string	No	Optional issue note.
evidence_file_ids	array	No	Optional evidence when an issue is reported.

Example response

{ "transaction_id":"txn_...", "receipt_status":"received_and_accepted", "confirmed_at":"2026-08-29T16:40:00Z" }

15. API reference - release and payout

POST /transactions/{transaction_id}/release

Request fund release

Request release of eligible funds according to the accepted terms. The public guide describes buyer confirmation followed by release to the seller, with broker commission released in the same step when applicable.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	payouts:write

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Request body

Field	Type	Required	Description
amount	decimal string	No	Omit for full eligible release; required for authorized partial/milestone release.
reason	enum	Yes	buyer_confirmation, milestone_met, auto_release, administrative_resolution.
milestone_id	string	No	Required for milestone release where applicable.
metadata	object	No	Non-sensitive reconciliation fields.

Example response

{ "id":"rel_01J...", "object":"release", "status":"processing", "gross_amount":"12500.00", "seller_amount":"12250.00", "commission_amount":"250.00", "currency":"CAD" }

Endpoint-specific errors

Code	HTTP	Meaning
release_conditions_not_met	409	Required approval, inspection or milestone condition is incomplete.
dispute_hold	409	Transaction is held by an open dispute.
already_released	409	Requested amount has already been released.
invalid_amount	422	Release amount exceeds eligible balance.

GET /transactions/{transaction_id}/releases

List releases

List release operations and payout allocation for a transaction.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	payouts:read

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

GET /releases/{release_id}

Retrieve release

Retrieve release processing and beneficiary allocation details.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	payouts:read

Parameters

Name	In	Type	Required	Description
release_id	path	string	Yes	Release ID.

16. API reference - refunds and cancellations

POST /transactions/{transaction_id}/refunds

Create refund

Create a full or partial refund when funds are available for return and policy/state permits it.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	refunds:write

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Request body

Field	Type	Required	Description
amount	decimal string	Yes	Refund amount.
reason	enum	Yes	cancelled, returned, duplicate, adjustment, dispute_resolution, other.
note	string	No	Operational note.
evidence_file_ids	array	No	Supporting evidence if required.

Example response

{ "id":"rfd_01J...", "status":"processing", "amount":"500.00", "currency":"CAD" }

Endpoint-specific errors

Code	HTTP	Meaning
amount_exceeds_refundable	422	Refund exceeds remaining refundable balance.
invalid_state	409	Refund is not permitted in current state.
release_conflict	409	Funds are no longer available for ordinary refund; another resolution path is required.

GET /transactions/{transaction_id}/refunds

List refunds

List refunds and current status.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	transactions:read

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

17. API reference - disputes

POST /transactions/{transaction_id}/disputes

Open dispute

Open a dispute and place the transaction into dispute handling where permitted.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	disputes:write

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Request body

Field	Type	Required	Description
reason	enum	Yes	not_received, not_as_described, damaged, incomplete, unauthorized_release, other.
summary	string	Yes	Concise factual description.
amount_disputed	decimal string	No	Amount at issue.
evidence_file_ids	array	No	Initial evidence.
external_reference	string	No	Your case/reference ID.

Example response

{ "id":"dsp_01J...", "status":"open", "transaction_id":"txn_...", "response_due_at":"2026-09-03T23:59:59Z" }

Endpoint-specific errors

Code	HTTP	Meaning
dispute_window_closed	409	Contractual or policy dispute period has elapsed.
invalid_state	409	A dispute cannot be opened in the current state.
duplicate_dispute	409	An active dispute already covers this issue.

GET /disputes/{dispute_id}

Retrieve dispute

Return case status, deadlines, requested evidence and resolution details.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	disputes:read

Parameters

Name	In	Type	Required	Description
dispute_id	path	string	Yes	Dispute ID.

POST /disputes/{dispute_id}/evidence

Submit dispute evidence

Associate uploaded evidence and a structured statement with an open dispute.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	disputes:write

Parameters

Name	In	Type	Required	Description
dispute_id	path	string	Yes	Dispute ID.

Request body

Field	Type	Required	Description
file_ids	array	Yes	Previously uploaded file IDs.
statement	string	No	Factual explanation of the evidence.
evidence_type	enum	Yes	invoice, proof_of_delivery, inspection, correspondence, identity, contract, other.

GET /transactions/{transaction_id}/disputes

List transaction disputes

List disputes associated with a transaction.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	disputes:read

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

18. API reference - brokers and commissions

Broker commissions are contractual allocations associated with a transaction. The public guide states that a transaction may contain your commission and that RBC Pay can release the commission in the same release step as seller funds.

POST /transactions/{transaction_id}/commissions

Create commission

Attach a broker/partner commission before acceptance locks material financial terms.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	transactions:write

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

Request body

Field	Type	Required	Description
broker_party_id	string	Yes	Broker participant ID.
type	enum	Yes	fixed or percentage.
amount	decimal string	Conditional	Required for fixed.
percentage	decimal string	Conditional	Required for percentage.
cap_amount	decimal string	No	Optional maximum.
description	string	No	Commission description.

Endpoint-specific errors

Code	HTTP	Meaning
terms_locked	409	Commission cannot change after terms lock without re-acceptance.
commission_exceeds_limit	422	Commission violates configured/contractual limit.

GET /transactions/{transaction_id}/commissions

List commissions

Return commission allocations and payout status.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	transactions:read

Parameters

Name	In	Type	Required	Description
transaction_id	path	string	Yes	Transaction ID.

19. API reference - files and evidence

POST /files

Upload file metadata / initiate upload

Create an upload object for transaction documents, invoices, proof of delivery, inspection records or dispute evidence. Large-file transport may use a pre-signed upload URL.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	files:write

Request body

Field	Type	Required	Description
purpose	enum	Yes	transaction_document, invoice, proof_of_delivery, inspection, dispute_evidence, other.
filename	string	Yes	Original file name.
content_type	string	Yes	MIME type.
size_bytes	integer	Yes	Declared size.
sha256	string	Recommended	Hex-encoded SHA-256 digest.
transaction_id	string	No	Transaction association.
dispute_id	string	No	Dispute association.

Example response

{ "id":"file_01J...", "status":"pending_upload", "upload_url":"https://...signed...", "expires_at":"2026-08-26T19:00:00Z" }

Endpoint-specific errors

Code	HTTP	Meaning
unsupported_file_type	422	File type is not accepted.
file_too_large	413	File exceeds configured limit.
malware_detected	422	Uploaded content failed security scanning.

GET /files/{file_id}

Retrieve file metadata

Return metadata and processing/security-scan status. Download URLs, when permitted, are short-lived.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	transactions:read or disputes:read as applicable

Parameters

Name	In	Type	Required	Description
file_id	path	string	Yes	File ID.

20. API reference - webhooks

POST /webhook-endpoints

Create webhook endpoint

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	webhooks:manage

Request body

Field	Type	Required	Description
url	url	Yes	Public HTTPS endpoint.
enabled_events	array	Yes	Specific event types or approved wildcard.
description	string	No	Operational description.

Example response

{ "id":"wh_01J...", "url":"https://merchant.example.com/webhooks/rbcpay", "status":"enabled", "secret":"whsec_..." }

Endpoint-specific errors

Code	HTTP	Meaning
invalid_url	422	URL is invalid, non-HTTPS or otherwise prohibited.
event_not_supported	422	Requested event type is not supported.

GET /webhook-endpoints

List webhook endpoints

List registered endpoints.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	webhooks:manage

PATCH /webhook-endpoints/{webhook_endpoint_id}

Update webhook endpoint

Change URL, event subscriptions or enabled state.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	webhooks:manage

Parameters

Name	In	Type	Required	Description
webhook_endpoint_id	path	string	Yes	Webhook endpoint ID.

POST /webhook-endpoints/{webhook_endpoint_id}/rotate-secret

Rotate webhook secret

Issue a new webhook signing secret. Support an overlap period if the developer portal allows dual-secret verification.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	webhooks:manage

Parameters

Name	In	Type	Required	Description
webhook_endpoint_id	path	string	Yes	Webhook endpoint ID.

GET /webhook-deliveries

List webhook deliveries

Inspect webhook delivery history for debugging and reconciliation.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	webhooks:manage

Parameters

Name	In	Type	Required	Description
endpoint_id	query	string	No	Filter by endpoint.
event_id	query	string	No	Filter by event.
status	query	enum	No	delivered, failed, pending.

POST /webhook-deliveries/{delivery_id}/replay

Replay webhook delivery

Request redelivery of a historical event to its configured endpoint.

Property	Requirement
Authentication	Bearer token
Idempotency	Required
Required scope	webhooks:manage

Parameters

Name	In	Type	Required	Description
delivery_id	path	string	Yes	Webhook delivery ID.

21. API reference - events and audit trail

GET /events

List events

Read immutable event records for reconciliation and audit. This is useful when webhook delivery was delayed or your receiver was unavailable.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	events:read

Parameters

Name	In	Type	Required	Description
type	query	string	No	Filter by event type.
resource_id	query	string	No	Filter by transaction or related resource.
created_from	query	timestamp	No	Lower time bound.
created_to	query	timestamp	No	Upper time bound.
starting_after	query	string	No	Cursor.
limit	query	integer	No	Page size.

Example response

{ "object":"list", "data":[{"id":"evt_01J...","type":"transaction.funded","created_at":"2026-08-27T10:15:00Z","data":{"object":{"id":"txn_..."}}}], "has_more":false }

GET /events/{event_id}

Retrieve event

Retrieve one immutable event envelope.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	events:read

Parameters

Name	In	Type	Required	Description
event_id	path	string	Yes	Event ID.

22. API reference - health and metadata

GET /health

API health check

Return a lightweight service status for integration monitoring. Do not use this endpoint as proof of transaction or payment state.

Property	Requirement
Authentication	May be public or authenticated according to deployment policy
Idempotency	Not applicable

Example response

{ "status":"ok", "api_version":"v1", "time":"2026-08-26T18:42:31Z" }

GET /capabilities

Retrieve integration capabilities

Return enabled currencies, transaction features, file constraints or account-specific capabilities when exposed.

Property	Requirement
Authentication	Bearer token
Idempotency	Not applicable
Required scope	transactions:read

Example response

{ "currencies":["CAD","USD"], "features":{"milestones":true,"broker_commissions":true,"disputes":true} }

23. Error model

A failed request returns an HTTP status plus a machine-readable JSON error. Integrations must branch on the stable error code, not on human-readable message text. The public guide illustrates this with a 422 invalid_currency error.

{
  "error": {
    "code": "invalid_currency",
    "message": "The currency is not supported for this transaction.",
    "field": "currency",
    "request_id": "req_01J...",
    "details": {}
  }
}

HTTP	Use	Typical causes
400	Bad Request	Malformed JSON, unsupported parameter shape, invalid query syntax.
401	Unauthorized	Missing/expired/invalid token.
403	Forbidden	Token valid but scope, account or role lacks permission.
404	Not Found	Resource absent or not visible to credentials.
409	Conflict	State conflict, duplicate operation, stale terms version.
413	Payload Too Large	Upload/request exceeds limit.
415	Unsupported Media Type	Incorrect Content-Type.
422	Unprocessable Entity	Semantically invalid field or business rule.
429	Too Many Requests	Rate limit reached.
500	Internal Server Error	Unexpected server failure.
502	Bad Gateway	Upstream dependency failure.
503	Service Unavailable	Temporary service unavailability.
504	Gateway Timeout	Upstream operation timed out.

23.1 Common application error codes

Code	Meaning	Client action
invalid_request	Malformed or incomplete request.	Correct request; do not retry unchanged.
invalid_currency	Unsupported currency.	Use supported currency/capability.
invalid_amount	Amount invalid or outside configured limits.	Correct amount.
invalid_state	Resource cannot perform action in current state.	Retrieve latest state and follow permitted transition.
version_mismatch	Terms version is stale.	Retrieve current transaction and re-present terms.
idempotency_conflict	Same key was reused with different request body.	Use original body or a new key for a new operation.
not_authorized	Actor/scope lacks permission.	Correct scopes/role; do not brute-force retry.
rate_limited	Request limit exceeded.	Honor Retry-After and back off.
temporarily_unavailable	Transient service/dependency issue.	Retry with bounded exponential backoff.
dispute_hold	Funds cannot release because dispute is open.	Follow dispute workflow.

24. Rate limits

The public RBC Pay guide states that requests are rate-limited per credential set and that 429 Too Many Requests is returned when the limit is reached. Production limits can vary by account, endpoint class and risk profile.

Design to the response headers and 429 behavior rather than hard-coding a single global limit.

Use event-driven updates instead of aggressive polling.

Batch reconciliation with paginated list endpoints and time filters.

Apply exponential backoff and honor Retry-After.

Do not invent production limits Publish numeric rate-limit values only after they are configured and verified in the gateway. This reference intentionally defines behavior without claiming an unverified requests-per-second number.

25. Webhook security and replay protection

Webhooks keep your system synchronized with transaction events. A receiver must authenticate every webhook before changing local state.

RBCPay-Signature: t=1787769720,v1=hex_hmac_sha256_signature
RBCPay-Event-ID: evt_01J...

25.1 Signature verification algorithm

Read the raw request body bytes exactly as received. Do not parse and reserialize before verification.

Parse the timestamp t and v1 signatures from RBCPay-Signature.

Reject timestamps outside your configured tolerance, typically a few minutes, to reduce replay risk.

Compute HMAC-SHA256(secret, timestamp + “.” + raw_body).

Compare expected and supplied signatures using constant-time comparison.

Deduplicate using the immutable event ID. Store processed event IDs before or atomically with business-side effects.

Return a 2xx quickly after durable acceptance; perform long-running work asynchronously inside your own system.

25.2 Example webhook event

{
  "id": "evt_01J6D...",
  "object": "event",
  "type": "transaction.status_changed",
  "created_at": "2026-08-27T10:15:00Z",
  "data": {
    "object": {
      "id": "txn_00000000",
      "object": "transaction",
      "status": "funded"
    },
    "previous_attributes": {"status": "funding_pending"}
  }
}

26. Integration recipes

26.1 Standard buyer-seller transaction

Create the transaction with amount, currency, buyer, seller, items and terms.

Submit the transaction and wait until every required party accepts the current acceptance_version.

Create funding instructions and direct the buyer through the approved funding method.

Wait for transaction.funded / confirmed funding. Never infer funding from a submitted bank transfer.

Allow the seller to fulfil only after confirmed funding if that is the agreed workflow.

Submit carrier/tracking or other fulfilment evidence.

Wait for delivery and buyer confirmation, contractual inspection expiry or another release condition.

Request release with an idempotency key.

Reconcile release/payout events and commission allocations.

26.2 Brokered transaction

Create the broker as a transaction participant and add commission terms before final acceptance. The commission becomes part of the accepted financial terms. When the release occurs, reconcile seller and broker allocations separately even if they are triggered by one release operation.

26.3 Milestone transaction

Represent the total transaction amount and milestone schedule in the accepted terms. Each milestone must have an objective completion condition, eligible amount and approval rule. Release only the eligible milestone amount, preserving the remaining secured balance.

26.4 Buyer reports a problem

Record receipt with issue, open a dispute before any automatic or ordinary release occurs, upload evidence, and stop local fulfilment completion logic until the dispute status resolves. Your system must treat the RBC Pay dispute/release state as authoritative.

27. SDK patterns and code examples

27.1 cURL - retrieve transaction

curl https://api.rbcpay.com/v1/transactions/txn_01J6C2A9T4... \
  -H "Authorization: Bearer $RBCPAY_TOKEN" \
  -H "Accept: application/json"

27.2 Node.js - create transaction

const response = await fetch('https://api.rbcpay.com/v1/transactions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.RBCPAY_TOKEN}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({
    title: 'Server equipment purchase',
    amount: '12500.00',
    currency: 'CAD',
    buyer: { email: 'buyer@example.com' },
    seller: { email: 'seller@example.com' },
    items: [{ name: 'Server equipment', quantity: 1 }],
    terms: { inspection_period_hours: 48, release_policy: 'buyer_confirmation' }
  })
});
if (!response.ok) throw new Error(await response.text());
const transaction = await response.json();

27.3 Python - safe request/retry skeleton

import os, time, uuid, requests

url = 'https://api.rbcpay.com/v1/transactions'
headers = {
    'Authorization': f"Bearer {os.environ['RBCPAY_TOKEN']}",
    'Content-Type': 'application/json',
    'Idempotency-Key': str(uuid.uuid4()),
}
payload = {
    'title': 'Server equipment purchase',
    'amount': '12500.00',
    'currency': 'CAD',
    'buyer': {'email': 'buyer@example.com'},
    'seller': {'email': 'seller@example.com'},
    'items': [{'name': 'Server equipment', 'quantity': 1}],
    'terms': {'inspection_period_hours': 48, 'release_policy': 'buyer_confirmation'},
}
for attempt in range(5):
    r = requests.post(url, json=payload, headers=headers, timeout=20)
    if r.status_code not in (429, 500, 502, 503, 504):
        r.raise_for_status(); break
    time.sleep(min(2 ** attempt, 16))
transaction = r.json()

27.4 Webhook verification pseudocode

raw = request.raw_body
sig = request.headers['RBCPay-Signature']
timestamp, supplied = parse_signature(sig)
assert abs(now_unix() - timestamp) <= tolerance_seconds
expected = hmac_sha256(webhook_secret, str(timestamp) + '.' + raw)
assert constant_time_equal(expected, supplied)
event = json_parse(raw)
assert not already_processed(event['id'])
process_idempotently(event)
return 200

28. Sandbox and test scenarios

Every integration should be built and tested against the sandbox before production credentials are enabled. Sandbox behavior should mimic production state transitions while avoiding real money movement.

Scenario	Expected test
Successful transaction	Create -> accept -> fund -> fulfil -> confirm -> release.
Duplicate POST	Retry same Idempotency-Key and verify only one resource/effect exists.
Idempotency conflict	Reuse a key with changed body and expect conflict.
Funding delay	Remain funding_pending until confirmed event.
Webhook outage	Return failures, then replay deliveries and ensure event deduplication.
Out-of-order webhooks	Process using resource version/status and event timestamps; reconcile via GET.
Terms change	Modify material terms and verify previous acceptance is superseded.
Dispute before release	Open dispute and verify ordinary release is blocked.
Partial refund	Refund less than eligible balance and reconcile remaining amount.
429 throttling	Verify backoff and Retry-After behavior.
5xx transient error	Retry boundedly with same idempotency key.
Expired token	Refresh token via OAuth flow and retry safely.
Invalid signature	Reject webhook without state change.
Replay attack	Reject or dedupe reused event ID/timestamp.

29. Production readiness checklist

Production secrets are stored in a managed secret store and excluded from logs/source control.

Outbound production IPs are stable and allowlisted where required.

OAuth scopes follow least privilege.

Every creation/money-movement write uses persisted idempotency keys.

Webhook signatures are verified against the raw body with timestamp tolerance.

Webhook event IDs are deduplicated transactionally.

Your system reconciles webhook events against GET endpoints before irreversible actions when necessary.

Timeouts, 429s and 5xx failures use bounded exponential backoff.

All money calculations use decimal or integer minor-unit arithmetic.

Production and sandbox credentials/data are fully separated.

Operational dashboards track error rate, latency, webhook failures, stale funded transactions and unreconciled payouts.

Support tooling records RBC Pay request IDs and your correlation IDs.

Dispute and refund workflows are tested end-to-end.

Sensitive data retention and access controls have been reviewed.

Runbooks exist for credential compromise, webhook outage, stuck release, funding mismatch and duplicate local processing.

30. Data protection and operational security

30.1 Data classification

Class	Examples	Handling
Secret	Client secret, bearer token, webhook signing secret.	Never log; encrypt at rest; strict access; rotate.
Restricted	Identity evidence, financial documents, dispute evidence.	Encrypt; purpose-limited access; retention controls; audit access.
Confidential	Transaction terms, commercial pricing, party contact data.	Authenticated access; minimize exposure and exports.
Operational	Resource IDs, timestamps, non-sensitive statuses.	May be logged with retention and access controls.

30.2 Security incident response

Revoke or rotate exposed credentials immediately.

Preserve request IDs, event IDs and audit logs needed to determine scope.

Do not delete or alter transaction records as a substitute for containment.

Coordinate with RBC Pay support using request IDs and affected resource IDs, not secrets.

31. Versioning and deprecation

The base URL is versioned using /v1. Backward-incompatible changes belong in a new major API version or a formally announced compatibility mechanism. Additive optional response fields can appear without breaking version.

Clients must ignore unknown JSON response fields unless a signed schema contract says otherwise.

Do not rely on JSON object field order.

New enum values can be introduced; use a safe fallback path for unknown non-terminal values.

Deprecations should include announcement date, replacement, migration guide and sunset date.

32. Glossary

Term	Definition
Acceptance version	Version number identifying the exact material terms a party accepted.
Buyer	Party providing funds and receiving goods/services/rights under the transaction.
Seller	Party fulfilling the transaction and receiving eligible released funds.
Broker	Authorized intermediary whose commission is defined in transaction terms.
Funding intent	Object describing the process/instructions to fund a transaction.
Funded	Authoritative state meaning required funds are confirmed under the platform workflow.
Fulfilment	Shipment, delivery, service completion or another contract performance action.
Inspection period	Contractual time window for buyer review after delivery, where applicable.
Release	Authorized movement/allocation of eligible secured funds to seller/beneficiaries.
Refund	Return of eligible transaction funds.
Dispute	Formal case that can alter or hold the ordinary release path.
Webhook	Signed HTTP event delivery from RBC Pay to the integration.
Idempotency key	Client-provided key that prevents duplicate side effects when retrying the same write.

Appendix A. Status codes

Resource	Status	Description
Transaction	draft	Terms are editable.
Transaction	pending_acceptance	Required party acceptance incomplete.
Transaction	accepted	Required current terms accepted.
Transaction	funding_pending	Funding is in progress.
Transaction	funded	Required funding confirmed.
Transaction	in_fulfilment	Seller fulfilment underway.
Transaction	delivered	Delivery/fulfilment reported complete.
Transaction	release_pending	Release is processing.
Transaction	released	Eligible funds released.
Transaction	disputed	Dispute handling active.
Transaction	partially_refunded	Some funds refunded.
Transaction	refunded	Refund completed for eligible total.
Transaction	cancelled	Transaction cancelled.
Transaction	closed	Workflow closed.
Funding	pending	Funding instructions issued / awaiting completion.
Funding	processing	Payment rail processing.
Funding	confirmed	Funds confirmed.
Funding	failed	Funding failed.
Release	pending	Release requested.
Release	processing	Release/payout processing.
Release	completed	Release completed.
Release	failed	Release failed and requires recovery/review.
Dispute	open	Case opened.
Dispute	evidence_required	One or more parties must submit evidence.
Dispute	under_review	Case being reviewed.
Dispute	resolved_buyer	Resolution favors buyer according to case decision.
Dispute	resolved_seller	Resolution favors seller according to case decision.
Dispute	resolved_split	Funds allocated by split resolution.
Dispute	closed	Case closed.

Appendix B. Event catalogue

Event type	When emitted
transaction.created	A transaction is created.
transaction.updated	Mutable transaction data changes.
transaction.submitted	Transaction submitted for acceptance.
transaction.accepted	Required terms acceptance becomes complete.
transaction.rejected	A required party rejects terms.
transaction.status_changed	Transaction status changes.
funding.created	Funding intent/instruction created.
funding.processing	Funding begins processing.
transaction.funded	Required funds become confirmed.
funding.failed	Funding attempt fails.
fulfilment.created	Seller/authorized actor reports fulfilment.
fulfilment.updated	Tracking or fulfilment status changes.
transaction.delivered	Delivery/fulfilment completion recorded.
transaction.receipt_confirmed	Buyer confirms receipt/acceptance.
release.created	Release request created.
release.completed	Release/payout allocation completes.
release.failed	Release processing fails.
refund.created	Refund created.
refund.completed	Refund completes.
refund.failed	Refund fails.
dispute.created	Dispute opened.
dispute.updated	Dispute stage/evidence status changes.
dispute.resolved	Dispute decision recorded.
transaction.cancelled	Transaction cancelled.
webhook.delivery_failed	Webhook delivery exhausted immediate attempts / requires inspection, if exposed.

Appendix C. Example end-to-end transaction

C.1 Create

POST /transactions  ->  201 Created
status: pending_acceptance

C.2 Accept

POST /transactions/txn_.../accept  (buyer)
POST /transactions/txn_.../accept  (seller)
-> status: accepted

C.3 Fund

POST /transactions/txn_.../funding-intents
-> funding status: pending
... verified event arrives ...
transaction.funded
-> transaction status: funded

C.4 Fulfil

POST /transactions/txn_.../fulfilments
carrier: DHL
tracking_number: 1234567890
-> status: in_fulfilment
... delivery event ...
-> status: delivered

C.5 Confirm and release

POST /transactions/txn_.../confirm-receipt
confirmation: received_and_accepted
POST /transactions/txn_.../release
reason: buyer_confirmation
-> release processing
... release.completed ...
-> transaction status: released

C.6 Reconcile

Persist the RBC Pay transaction ID, release ID, seller allocation, commission allocation, event IDs and request IDs alongside your internal order or deal record. Reconciliation must be able to prove that one local order maps to one intended transaction workflow and that retries did not create duplicate financial effects.

Appendix D. Source and implementation notes

Public source consulted: RBC Pay, “API Guide,” https://www.rbcpay.com/api-guide/, accessed August 26, 2026. The public page establishes the API’s stated REST/HTTPS/JSON model, OAuth 2.0 bearer authentication, server-side credential handling, base URL https://api.rbcpay.com/v1, transaction creation example, webhook concept/example, JSON error pattern, per-credential rate limiting, sandbox testing, and a six-step transaction lifecycle.

This document deliberately goes further than the current public page. Endpoint paths, object fields, scopes, webhook signature format, dispute resources, file resources, funding objects, release objects and detailed status catalogues that are not explicitly published on the current public page are presented as the RBC Pay v1 reference specification. Before publishing this manual as production documentation, the API gateway, backend services, developer portal, webhook signer and support runbooks should be validated against the contract in this document.

Publication gate A developer reference is a promise. Do not publish an endpoint, rate limit, scope, event type or security header until the deployed system behaves exactly as documented, or revise this document to match production.

Developer quick reference

Need	Endpoint / action
Authenticate	POST /oauth/token
Create transaction	POST /transactions
Read transaction	GET /transactions/{id}
Submit for acceptance	POST /transactions/{id}/submit
Accept terms	POST /transactions/{id}/accept
Create funding	POST /transactions/{id}/funding-intents
Check funding	GET /transactions/{id}/funding
Report fulfilment	POST /transactions/{id}/fulfilments
Confirm receipt	POST /transactions/{id}/confirm-receipt
Release funds	POST /transactions/{id}/release
Refund	POST /transactions/{id}/refunds
Open dispute	POST /transactions/{id}/disputes
Upload evidence	POST /files
Register webhook	POST /webhook-endpoints
Reconcile events	GET /events

End of RBC Pay API Guide & Full API Reference v1.0

RBC Pay API v1 |

Ready to build with Rbcpay?

Get your sandbox credentials and run your first test transaction end to end before you switch to live.

Full API Guide

API guide and full API reference

Base URL

API version

Format

Authentication

Developer quick reference

Full API reference

Document control

Conventions used in this guide

1. Platform overview

1.1 Design principles

1.2 High-level architecture

2. Environments and base URLs

2.1 Transport requirements

3. Authentication and authorization

3.1 Recommended OAuth flow

3.2 Scopes

3.3 Token handling

4. Security requirements

4.1 IP allowlisting

4.2 Secret storage

4.3 Sensitive data minimization

4.4 Logging

5. Request conventions

5.1 Common request headers

5.2 Common response headers

5.3 Monetary fields

5.4 Dates and timestamps

6. Idempotency and retries

6.1 Retry policy

7. Pagination, filtering and expansion

7.1 Cursor pagination

7.2 Common filters

8. Transaction lifecycle and state machine

8.1 State-change rules

9. Core resource models

9.1 Transaction object

9.2 Item object

9.3 Terms object

9.4 Party object

10. API reference - authentication

Request body

Example request

Example response

Endpoint-specific errors

11. API reference - transactions

Request body

Example request

Example response

Endpoint-specific errors

Parameters

Example response

Endpoint-specific errors

Parameters

Example response

Parameters

Request body

Endpoint-specific errors

Parameters

Example response

Endpoint-specific errors

Parameters

Request body

Example response

Endpoint-specific errors

12. API reference - parties and acceptance

Parameters

Parameters

Request body

Endpoint-specific errors

Parameters

Request body

Example response

Endpoint-specific errors

Parameters

Request body

13. API reference - funding

Parameters

Request body