Funding Address & Collections

What is a funding address?

A funding address is a dedicated fiat account issued to one of your managed accounts. On most
rails this is a virtual account number; on MXN/SPEI it is a CLABE. Funds transferred into it are
credited to that managed account's balance.

Each managed account can create a funding address per currency and network. Requesting a funding address for a currency/network combination you have already opened returns the existing address rather than creating a second one.

Creating a funding address

sequenceDiagram
    participant C as Managed Account
    participant API as Reap
 
    C->>API: POST /api/funding/addresses
    alt Funding address already exists for the currency and network combination
        API-->>C: 200 OK with the existing funding address
    else New funding address
        API-->>C: 201 Created, status "pending"
        API-->>API: Process funding address creation
        API-->>C: Webhook triggered
        Note over API,C: "eventType": "funding_address"
        Note over API,C: "eventName": "funding_address_status_update"
        Note over API,C: "status": "active"
    end

Create a funding address with supported currency and network combination depending on your account setup. The call is idempotent: 201 means a new address was created, 200 means you already had one and we returned it.
A newly created address starts in pending and has no accountNo yet. Wait for the funding_address_status_update webhook (or poll the status via Get a funding address by id) until the status is active — at that point accountNo is populated and the address can receive funds.

Funding address lifecycle

stateDiagram-v2
    direction LR
 
    Pending: pending
    Active: active
    Failed: failed
    Rejected: rejected
 
    [*] --> Pending: POST /api/funding/addresses
    [*] --> Active: currency opened on an already-live account
 
    Pending --> Active: account provisioned
    Pending --> Failed: provisioning failed
    Pending --> Rejected: provisioning declined
 
    Failed --> Pending: retried
 
    Active --> [*]
    Rejected --> [*]

Status	Meaning
`pending`	The account has been requested but is not yet live. `accountNo` is not available yet
`active`	The account is live and can receive funds
`failed`	Provisioning failed. Contact the Reap team.
`rejected`	Provisioning was declined. This is terminal and is not retried — contact the Reap team

Every status change fires a funding_address_status_update webhook which is detailed here.

What is a collection?

A collection is a request for funds against an invoice. The pre-requisite for creating a collection is to have an active funding address. With that, you create a collection request against a registered payer, and Reap returns a hosted payment link. The payer retrieves the transfer details via the payment link and transfers the funds into the funding address. Upon receipt, Reap attributes the incoming funds to the collection and credits your balance accordingly.

A collection can be paid in more than one instalment. Each receipt is attributed as it arrives, and
the collection completes once the invoice amount is covered.

Creating a collection

sequenceDiagram
    participant EU as Payer
    participant C as Managed Account
    participant API as Reap
 
    C->>API: POST /api/collections/payers
    API-->>C: Return unique Payer ID
    C->>API: POST /api/collections
    C->>API: POST /api/collections/{collectionUuid}/documents
    API-->>API: Review and approve collection
    API-->>C: Webhook returns collection with paymentLink
    C->>EU: Share the payment link with transfer details
    EU->>API: Transfer funds
    API-->>API: Processes payment upon receipt
    API-->>C: Webhook triggered
    Note over API,C: "eventType": "collection"
    Note over API,C: "eventName": "collection_status_update"
    Note over API,C: "status": "partially_received" or "completed"

Payers are created once using the Create a collection payer endpoint. Thereafter, you can call the Create a collection endpoint and the response will return the collection id and a paymentLink — a hosted page (e.g. https://pay.reap.global/c/ABCDEFG123) showing the transfer instructions for each currency you allowed, including the transferReference which is needed for attribution of funds to the collection request.

Collection lifecycle

stateDiagram-v2
    direction TB
    Draft: draft
    UnderReview: under_review
    AwaitingFunds: awaiting_funds
    PartiallyReceived: partially_received
    Completed: completed
    Expired: expired
    Cancelled: cancelled
 
    [*] --> Draft: POST /api/collections

    Draft --> UnderReview: doc submitted and collection request under review
    UnderReview --> AwaitingFunds: collection request approved and link generated
 
    AwaitingFunds --> PartiallyReceived: part of the invoice received
    AwaitingFunds --> Completed: invoice amount received
    AwaitingFunds --> Cancelled: cancelled by you
    AwaitingFunds --> Expired: expiresAt passes
 
    PartiallyReceived --> PartiallyReceived: further partial receipt
    PartiallyReceived --> Completed: invoice amount covered
    PartiallyReceived --> Expired: expiresAt passes
 
    Completed --> [*]
    Expired --> PartiallyReceived
    Expired --> Completed
    Cancelled --> [*]

A collection is created in "Draft" status and enters "Under Review" when document is submitted.
The collection enters "Awaiting Funds" once the it is reviewed and approved. The payment link is returned at this stage.
When funds arrive, Reap attributes them to the collection and converts them into your balanceCurrency.
1. If the received total does not yet cover the invoice amount, the collection moves to "Partially Received" and stays open for further transfers. Each subsequent partial receipt fires another webhook.
2. Once the invoice amount is covered, the collection moves to "Completed".
3. Every webhook carries a receivedSummary with totalReceived and invoiceRemainingAmount, so you always know how much is still outstanding.
"Expired" is reached automatically once expiresAt passes, if the collection has not completed. Both "Awaiting Funds" and "Partially Received" collections expire; any funds already received stay credited.
"Cancelled" is reached by calling POST /api/collections/{collectionUuid}/cancel. A
collection can be cancelled while it is in "Draft", "Under Review" or "Awaiting Funds" — once any funds have been received, cancellation is no longer available.
"Completed" and "Cancelled" are both final states. For "Expired", even though the collection was not completed, if funds does arrive later, it will still be attributed accordingly.

A payer who transfers materially more than the invoice amount will not have the excess credited
automatically. The funding is held and the Reap team will arrange its return.

Status	Description
`draft`	The collection is created.
`under_review`	Document is submitted for the collection and it's currently being reviewed
`awaiting_funds`	The collection is approved and live, and is waiting for the payer to transfer
`partially_received`	Some funds have been received and credited, but the invoice amount is not yet covered
`completed`	The invoice amount has been received and credited
`expired`	`expiresAt` passed before the collection completed
`cancelled`	Cancelled by you before any funds were received

Every status change fires a collection_status_update webhook.