# Create a collection

Creates a new payment link for a collection using account-based routing. The collection
is associated with an account which determines the available payment rails and currency.
The amount is denominated in the account's currency.

Endpoint: POST /v1/collections/links
Version: 1.0.0
Security: Bearer

## Request fields (application/json):

  - `payer_id` (string, required)
    Unique identifier of the payer partner
    Example: "0c5479ff-3772-4123-b2b7-e679e71eb570"

  - `account_id` (string, required)
    Unique identifier of the account to receive funds
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  - `amount` (string, required)
    Collection amount as a string to preserve precision
    Example: "800.00"

  - `fee_mode` (string)
    How fees are handled in the collection
    Enum: "INCLUDED", "EXCLUDED"

  - `reference_id` (string)
    External reference identifier for the collection
    Example: "INV-2025-009"

  - `description` (string)
    Human-readable description of the collection purpose
    Example: "Payment for Order #2668"

  - `link_expiry` (integer, required)
    Payment link expiry time in seconds from creation
    Example: 172800

  - `return_url` (string, required)
    URL to redirect user after payment completion
    Example: "https://example.com/payment/completion"

## Response 201 fields (application/json):

  - `id` (string, required)
    Unique identifier for the collection
    Example: "e8d43598-107d-4694-9fb2-934e7484c3d4"

  - `payer` (object, required)
    Payer partner details

  - `payer.id` (string, required)
    Unique identifier for the payer partner
    Example: "0c5479ff-3772-4123-b2b7-e679e71eb570"

  - `payer.name` (string, required)
    Full name of the payer partner
    Example: "Nigerian Imports Ltd."

  - `payer.email` (string, required)
    Email address of the payer partner
    Example: "nigerian@imports.com"

  - `beneficiary` (object, required)
    Beneficiary partner details

  - `beneficiary.id` (string, required)
    Unique identifier of the beneficiary partner
    Example: "01467076-8bb0-41c1-ad54-5751dd4a9e80"

  - `beneficiary.name` (string, required)
    Full name of the beneficiary partner
    Example: "Hong Kong Exports Ltd."

  - `beneficiary.email` (string, required)
    Email address of the beneficiary partner
    Example: "hongkong@exports.com"

  - `account` (object, required)
    Account associated to this collection, which funds will be routed to

  - `account.id` (string, required)
    Unique identifier for the account
    Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

  - `account.beneficiary_id` (string, required)
    Unique identifier of the beneficiary partner
    Example: "291ecf34-a01d-466a-b0fd-662a88b7a1bb"

  - `account.currency` (string, required)
    Currency for the account
    Example: "USD"

  - `account.type` (string, required)
    Type of account
    Enum: "FIAT", "CRYPTO"

  - `reference_id` (string)
    External reference identifier for the collection
    Example: "INV-2025-009"

  - `gross_amount` (string, required)
    Total amount including fees
    Example: "808.00"

  - `net_amount` (string, required)
    Amount excluding buyer fees
    Example: "800.00"

  - `fee_mode` (string, required)
    How fees are handled in the collection
    Enum: "INCLUDED", "EXCLUDED"

  - `fee` (string, required)
    Fee amount charged for the collection
    Example: "8.00"

  - `amount_remaining` (string, required)
    Amount remaining for an incomplete payment
    Example: "758.50"

  - `description` (string, required)
    Human-readable description of the collection purpose
    Example: "Payment for Order #2668"

  - `link_expiry` (integer, required)
    Payment link expiry time in seconds from creation
    Example: 172800

  - `return_url` (string, required)
    Example: "https://example.com/payment/completion"

  - `expires_at` (string, required)
    ISO 8601 timestamp when the collection expires
    Example: "2025-06-30T23:59:59Z"

  - `payment_link` (string)
    URL for the payment interface
    Example: "https://collections.ripple.com/link/pay/384c5f9b"

  - `status` (string, required)
    The status of the collection
    Enum: "CREATED", "CLOSED", "HOLD", "EXPIRED", "PENDING", "PROCESSING", "COMPLETED", "UNDERPAID", "OVERPAID", "CANCELLED"

  - `reason` (string,null)
    Reason for current status (if applicable)

  - `created_at` (string, required)
    ISO 8601 timestamp when the collection was created
    Example: "2025-06-17T12:00:00Z"

  - `updated_at` (string, required)
    ISO 8601 timestamp when the collection was last updated
    Example: "2025-06-17T12:30:00Z"

## Response 400 fields (application/json):

  - `code` (string, required)
    Error code identifying the type of error

  - `reason` (string, required)
    Human-readable error message