Collection

The payment gateway offers the ability to collect incoming payment. The collection process involves a few concepts that aren't used in payments or other operations.

Collections may be initiated by end users (mobile money subscribers, etc.) who want to send money, or by payment gateway clients. Collections initiated by clients are called invoices.

Reference Codes

When end users initiate collections, they send the money to a Segovia-managed account and include a "reference code" with the payment.

The payment gateway matches the beginning of the reference code against a list of prefixes. A prefix is a case-insensitive alphanumeric string between 4 and 10 characters long and must be claimed by a client before any payments are received. To claim a prefix, contact your Segovia account representative.

A prefix may not begin with another prefix that has already been claimed; that is, if a client has claimed prefix HIJKL, the prefix HIJKL123 is no longer available. Prefixes may not begin with the letter X or the digit 0.

Each client may claim a limited number of prefixes. The limit may be raised as needed; if your application needs to use a large number of prefixes, please contact Segovia.

For example, if a client has claimed a prefix of ABCD and a payment arrives with a reference code of ABCDEFGH, the payment is credited to the client and the entire reference code of ABCDEFGH is included in the transaction information.

The payment gateway doesn't require any characters to come after the prefix. If you don't need to differentiate between payments from a particular end user (e.g., because you look their account up using the mobile number the collection came from) you can direct the user to enter the prefix by itself as the reference code. For example, if an incoming payment has a reference of ABCD in the above example, it will still be credited to the client that claimed the ABCD prefix.

Invoices

When a client makes an invoice request, the payment gateway conducts an interaction with the end user and their payment provider, sending instructions to the user over SMS and receiving the incoming payment. It will generate a reference code using a Segovia-reserved prefix, and use that to match incoming payments to the invoice.

When the gateway receives a payment from an end user, it uses the payment's reference code to determine whether the payment corresponds to an outstanding invoice. If it does, the gateway considers the invoice completed and notifies the client with a callback. If not, it will use the prefix-based matching described above.

Note that, depending on the payment provider, it may be possible for the end user to pay an amount that differs from the amount requested in the original invoice. Regardless of amount, the gateway considers an invoice completed when it receives a payment with a reference code that matches that invoice.

User-Initiated Collections

The end user supplies the reference code field when initiating a payment; if you don't use invoices, it is up to you to communicate the correct code to them ahead of time. The payment is sent to a Segovia-managed account, the details of which vary by payment provider; Segovia will supply you with a collection account number or other recipient address to give to end users.

When the payment gateway receives an incoming payment from a payment provider, it compares the reference code to the list of prefixes for the payment provider. If the code starts with a known prefix, the payment is associated with the client that claimed the prefix.

If the client is able to receive collection confirmation callbacks and the payment provider allows rejection of incoming payments, the payment gateway sends a collection confirmation callback via HTTPS to the client with the details of the collection. The client either confirms or rejects the transaction, and the payment gateway attempts to communicate that decision to the payment provider. Note: This is not guaranteed to succeed; payment providers sometimes disregard rejection of incoming payments.

Assuming the client accepted the collection, or if the provider doesn't support rejection of incoming payments, the payment is recorded as a collection transaction in the payment gateway.

If the client is able to receive notifications, the gateway sends the transaction details via an HTTPS request to the client's collection notification URL. The transaction details may also be found in the payment gateway user interface or via the /api/transactionstatus API function.