Segovia Payment Gateway API 1.0 Reference

Introduction

Segovia’s payment gateway offers a unified API to interact with a range of payment services across multiple countries.

The API is language- and platform-independent. Requests are sent using HTTPS requests, and JSON is the data format for both input and responses. Responses are asynchronous and are sent using HTTPS requests from the payment gateway to the client. Transactions are sent in batches to efficiently support bulk-payment operations, but single-transaction batches are supported for use by clients that don’t need bulk payments.

Terminology

Callback: An HTTPS request sent by the gateway to the client.

Client: A system that sends requests to the gateway and receives results.

Client ID: A unique, Segovia-assigned identifier for a client.

Gateway: The software system described by this document, which provides a uniform API to multiple providers.

Payer: The entity that is sending money to recipients.

Payer account ID: An identifier associated with a payer for a particular provider. A single payer may have multiple account IDs with a single provider.

Provider (or Payment provider): A third-party company or service that distributes money to recipients.

Recipient: A person who receives money from a provider.

Recipient account ID: The identifier associated with a recipient for a particular provider. For mobile money providers, this would typically be the recipient’s phone number. A single physical recipient may have multiple account IDs, e.g., because they have more than one mobile phone or because they are served by multiple providers of different types.

Request: An HTTPS request sent by the client to the gateway.

Subscriber: An end user who receives money from a Segovia customer or sends money to a Segovia customer. For example, a mobile money account holder.

Subscriber account ID: The identifier associated with a subscriber for a particular provider. For mobile money providers, this would typically be the subscriber’s phone number. A single person or company may have multiple subscriber account IDs, e.g., because they have more than one mobile phone or because they are served by multiple providers of different types.

Transaction ID: A client-supplied unique string value that identifies a single transaction (where a "transaction" is an individual payment or other operation, not a batch). Transaction IDs may not be reused, not even for requests of different types, and it is an error to send a transaction with a previously-used ID. Though any string value may be used, a universally unique identifier (UUID) in canonical hexadecimal format is a recommended choice.

Requests

All requests are sent over HTTPS using the POST verb. Request and response bodies are in JSON format using UTF-8 encoding. The gateway will send UTF-8 regardless of the value of any HTTP Accept: header included in the request; this is to prevent ambiguous output if the client were to specify an encoding that wasn't capable of representing the text of the response.

Requests that ask the gateway to perform an action are processed asynchronously. HTTPS responses are always generated immediately. For any operation that is not guaranteed to complete instantly, the HTTPS response simply indicates that the request was received and was valid.

Each request must include an Authorization HTTP header and an API-Version HTTP header. Both are described below.

There are two ways to get results from API requests that perform actions: callbacks and polling.

Callbacks

Callback requests are the preferred way to receive results from the gateway.

Callbacks may be enabled on a per-client or a per-request basis. The result of the operation is transmitted to the client using one or more separate HTTPS requests ("callbacks") to a URL that is associated with the particular client. This allows the API to support operations that would take longer than a client’s request timeout, and allows a client to be restarted or become unreachable while requests are pending, which is particularly important for clients in regions with frequent Internet or power outages.

The results from a single client-to-gateway request can be spread across multiple gateway-to-client callback requests, e.g., if the original request contains a list of payment instructions some of which complete more quickly than others.

The gateway rate-limits its callbacks to avoid pummeling the client with requests; each callback request contains a list of updates. For any pending API request, the gateway will only send one callback request at a time, to prevent situations where clients could process concurrent callbacks in the wrong order.

The gateway may send any number of informational status updates to inform the client of the progress of the transactions in a request; the current states of individual transactions will be indicated by the transaction status codes as described in the "Transaction Status Codes" section. There will be exactly one non-informational status update for each transaction. When the client responds to that update with an HTTP 2xx response code, the gateway considers the transaction complete and will no longer issue further requests about it to the client, though the client may request its status explicitly using the /api/transactionstatus endpoint.

Not all transactions from a given request will necessarily be included in every callback; only transactions whose statuses have changed since the previous callback will be reported. A single callback may contain a mix of informational and final updates for different transactions. A transaction will never be mentioned more than once in a single callback. When all transactions have completed (whether successfully or not) the final callback will contain a flag indicating that it's the last one.

If the client is unreachable when the gateway attempts to make a callback request, the gateway will retry the callback request periodically for at least 3 days before discontinuing further attempts. In that case the status of individual transactions may be queried later using the /api/transactionstatus endpoint.

Each callback request includes a timestamp field in its body. This may be ignored by the client, but may also be used to detect attempted replay attacks; the gateway will never send two callback requests for the same API request with the same timestamp.

The sequence of HTTPS requests and responses looks like this:

Request sequence diagram

Result Polling

Callback requests require the client to be accessible from the public Internet so that the gateway can initiate connections to it, and they require that the client run an HTTPS server to accept requests from the gateway. In cases where one or the other of those requirements is prohibitive, the client may also poll for transaction results using the /api/transactionstatus endpoint.

The client may poll for status at any time; for each transaction, the most recently available status is returned. Client implementations should take a couple things into account:

  1. The gateway requires time to process a batch. If the client polls for the status of a transaction in a large batch before the gateway has gotten to that transaction, a "transaction not found" error status may be returned since the transaction in question won't have been processed yet. In that case the client should try again later.
  2. Each transaction status record includes a finished flag. Though the API doesn't forbid repeatedly querying the status of a transaction, it's more efficient to stop polling for the status of transactions once that flag is set; it indicates that there will be no further processing and that the current status is final.

It is permitted (though should usually be unnecessary) to poll for the status of transactions whose updates are also being sent to the client using callback requests.

Request Format

The body of every API request should be a single JSON object rendered using UTF-8 encoding. The exact contents of the object vary, but most requests include some common fields. These fields are listed in the documentation for individual API requests but described in more detail here.

Field Type Description
clientId String Segovia-assigned identifier of the client making the request. In addition to determining which account(s) to use to process the request, the secret key associated with this client ID is used to verify the request signature. Required.
requestId String A client-generated unique identifier for this request. This may be any arbitrary string value but must be unique; the gateway will reject a request with a previously-used ID. The request ID serves both as a key to look up request status and as a nonce that's included in the request signature to prevent replay attacks. A universally unique identifier (UUID) in canonical hexadecimal format is a recommended choice.
callbackArgs Any Value to be passed back to the client in all callback requests resulting from this API request. This may be any valid JSON value, including an object with an arbitrary set of fields, and its contents are not interpreted by the gateway, though the gateway may parse and rerender the value (which could result in side effects such as the order of fields in JSON objects changing).
callbackUrl String If supplied, this URL is used for callback requests. This may not be included in requests from clients whose callback URL is configured in the per-client configuration; this is to ensure that the client is informed of all requests performed on its behalf. May be up to 200 characters long.

String Values

Unless otherwise noted, all string values have a length limit of 100 characters.

Numeric Values

Internally, the gateway uses an arbitrary-precision representation for monetary amounts and other non-integer numeric values, so there is no danger of floating-point errors. The client may supply numeric values in string form if desired; the values 1234.56 and "1234.56" are considered equivalent for any field whose type is listed as "Decimal" in this document. Numbers formatted as strings must be formatted the same way as non-string JSON numbers: no currency symbol and no punctuation other than a single period character separating the whole and fractional parts.

JSON is of course a textual representation and doesn't mandate an application's internal data types. Using floating-point types to represent monetary amounts is generally considered bad practice because their precision is limited and errors can be introduced in arithmetic operations.

API Version

Every API request must contain an API version number in the API-Version HTTP header line. This document describes version 1.0 of the API, so the header should be

API-Version: 1.0

Request Signature

Every API request must contain a signature in the Authorization HTTP header line, which should have the format

Authorization: Segovia signature=(signature value)

The signature value is computed as follows:

  1. Compute the HMAC-SHA256 digest of the request body (JSON in UTF-8 encoding) using the correct secret key for request signing.

  2. Render the digest value as a string of hexadecimal digits. The gateway is case-insensitive when verifying signatures.

Do not include the secret key in the request body! It should only be supplied as an input to the HMAC-SHA256 computation.

Example Code

Java (with Jackson JSON serialization and JDK HTTP client)

// Serialize the request parameters to JSON in a byte array.
ObjectMapper mapper = new ObjectMapper();
byte[] requestBody = mapper.writeValueAsBytes(requestParams);

// Sign the request body using HMAC-SHA256.
Mac hmac = Mac.getInstance("HmacSHA256");
SecretKeySpec key = new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256");
hmac.init(key);
byte[] signatureBytes = hmac.doFinal(requestBody);

// Render the Authorization header's value.
String signature = DatatypeConverter.printHexBinary(signatureBytes);
String headerValue = String.format("Segovia signature=%s", signature);

// Open a connection to the payment gateway and set the required HTTP headers.
URL url = new URL("https://payment-api.thesegovia.com/api/pay");
URLConnection connection = url.openConnection();
connection.setDoOutput(true);
connection.setRequestProperty("API-Version", "1.0");
connection.setRequestProperty("Authorization", headerValue);
connection.setRequestProperty("Content-Length", String.valueOf(requestBody.length));
connection.setRequestProperty("Content-Type", "application/json");

// Send the request body (in JSON form) to the payment gateway.
OutputStream out = connection.getOutputStream();
out.write(requestBody);
out.close();

// Read the response. You may prefer to deserialize to a class that has the fields
// you expect to get back; this example deserializes to a generic Map object.
InputStream in = connection.getInputStream();
Map<String, Object> result = mapper.readValue(in, Map.class);
in.close();

// Examine result and do whatever your application needs to do.

PHP

// Encode the request parameters as a JSON string.
$post_body = json_encode($request_parameters);

// Sign the request body using HMAC-SHA256.
$hmac_signature = hash_hmac('sha256', $post_body, $secret_key);

// Render the Authorization header's value.
$authorization = 'Segovia signature=' . $hmac_signature;

// Set up the URL and header lines.
$url = 'https://payment-api.thesegovia.com/api/pay';
$headers = array(
    'API-Version: 1.0',
    'Authorization: ' . $authorization,
    'Content-Type: application/json'
);

$curl_handle = curl_init($url);
curl_setopt_array($curl_handle, array(
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $post_body,
    CURLOPT_RETURNTRANSFER => true
));

// Send the request and read the response from the payment gateway.
$response = curl_exec($curl_handle);
if ($response === false) {
    print('Error sending request: ' . curl_error($curl_handle) . '\n');
} else {
    $result = json_decode($response);
}

// Close the cURL handle to release system resources.
curl_close($curl_handle);

// Examine $result and do whatever your application needs to do.

Python 3 (with Requests library)

import hmac
import json
import requests

# Encode the request parameters as a JSON string.
request_body = json.dumps(request_params).encode('UTF-8')

# Sign the request body using HMAC-SHA256.
digest = hmac.new(secret_key.encode('UTF-8'), msg=request_body, digestmod='SHA256')

# Render the Authorization header's value.
signature = digest.hexdigest()
authorization = 'Segovia signature={0}'.format(signature)

# Set up the URL and header lines.
url = 'https://payment-api.thesegovia.com/api/pay'
headers = {
    'API-Version': '1.0',
    'Authorization': authorization,
    'Content-Type': 'application/json'
}

# Send the request and read the response from the payment gateway.
response = requests.post(url, data=request_body, headers=headers)
result = response.json()

# Examine result and do whatever your application needs to do.

API Functions

/api/balance

Queries the current balances of the wallets used for managed payments. This request is synchronous; the gateway returns results directly in the HTTPS response rather than using callbacks.

See the Wallets page for information about how wallets work.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
walletId String Restrict the results to a particular wallet and/or subwallet. This is in path format, main-wallet-name/subwallet-name. Either the main wallet or subwallet part of the ID may be replaced with an asterisk * to query either all the subwallets under a particular main wallet or all the subwallets of a particular name across all main wallets. If this isn't specified, all wallets and subwallets are queried.
includeDeactivated Boolean If true, deactivated subwallets are included in the results. If not present or false, only main wallets and activated subwallets are included.

Response Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String The client ID specified in the request. Required.
wallets Array An array of objects with information about the wallet(s) available to the client. Required.

Each element in the wallets array is an object with the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
walletId String The wallet or subwallet's unique identifier. Required.
currency String ISO-4217 currency code of the currency held by this wallet. All amounts are in units of this currency. Required.
currentBalance Decimal The amount of money in the wallet. Required.
availableBalance Decimal The amount of money available to send to recipients. May be less than currentBalance if there are transactions currently in process. Required.
minimumBalance Decimal The minimum available balance required to initiate a new payment. Required.
negativeBalanceLimit Decimal How far below zero the wallet's balance is allowed to go. Required.
activated Boolean If true, this subwallet is currently activated. Always true for main wallets.

/api/cancel

Cancels pending transactions if possible. In general, a transaction may be cancelled if it has not yet been sent to a payment provider. Typically this would be because the provider is offline or because the provider imposes a rate limit and the transaction is part of a large batch.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
callbackArgs Any Passed back to the client when the gateway transmits results.
callbackUrl String The URL to send callback requests to. May be up to 200 characters long. Ignored if a callback URL is configured for the client.
transactionIds Array An array of strings, the IDs of transactions to cancel. Required.

Callback Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String The client ID specified in the request. Required.
requestId String Client-generated unique identifier for this request, the same value that was included in the original request. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
callbackArgs Any If the client supplied this field in the initial request, it is included in the response.
finished Boolean true if the request is complete and this is the last callback for the request; false if the client should expect additional callbacks. Required.
transactions Array An array of JSON objects describing the results of the operation. Required.

Each element of the transactions array is a JSON object with the following fields.

Field Type Description
transactionId String The ID of the transaction. Required.
transactionType String One of invoice, lookup, pay, sms-send, or validate. Additional types may be added over time. Required
statusType String One of pending, succeeded, or failed. Required
statusCode Integer Numeric code indicating the current status of the transaction. See the "Transaction Status Codes" section. Required.
statusDescription String A human-readable description of the current status of the transaction. Required.
finished Boolean A boolean value indicating whether this transaction is now finished (either successfully or not as indicated by statusCode). No further updates for a finished transaction will be sent. Required.
provider String The Segovia-assigned ID of the payment provider, e.g., mtn-rwanda. This field will be present unless the original transaction was not found, or when autodetection was requested for the original transaction but wasn't successful.

/api/collect/invoice

Initiates a collection by requesting payment from specific end users. The process is described in further detail in Collection.

For each transaction in the batch, the payment gateway will generate a reference code that will be used to associate the invoice request with the incoming payment from the end user. The reference code will not use any of the client's assigned prefixes, but rather a Segovia-reserved prefix. The generated reference code for each transaction will be returned in callbacks related to that transaction, along with Segovia's collection account number on the payment provider for the transaction.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
callbackArgs Any Passed back to the client when the gateway transmits results.
callbackUrl String The URL to send callback requests to. May be up to 200 characters long. Ignored if a callback URL is configured for the client.
transactions Array The invoice transactions to send. Required.

Each element of the transactions array is a JSON object with the following fields.

Field Type Description
transactionId String A client-generated unique identifier for this transaction. Transaction IDs must be unique across all requests from a client regardless of request type. Required.
provider String The Segovia-assigned ID of the payment provider, e.g., safaricom-kenya, or autodetect to attempt to automatically detect the provider based on the recipient account ID. Required.
subscriberAccountId String The provider-assigned account ID of the party from whom to request payment. For mobile money collections, this should be the end user's mobile number including country code. Required.
amount Decimal The amount of money to request from the end user. Required.
currency String ISO 4217 currency code. Required.
name String The subscriber's name. Required.
reason String A description of the request, to be shown to the end user. This will be sent to the end user in an SMS message, so its length is limited to 30 characters.
walletId String Which wallet or subwallet to credit when the payment arrives, and to debit for the invoice fee. Be aware that wallets are often tied to payment providers; specifying a wallet ID that isn't valid for this payment's provider will result in an error. If this field isn't present, the payment gateway will select the appropriate main wallet for the payment provider.
otherParams Object Any additional parameters required by the payment provider and not covered by the fields above. Shouldn't be needed in most cases.

Callback Fields

The callback request contains the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String The client ID specified in the request. Required.
requestId String Client-generated unique identifier for this request, the same value that was included in the original request. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
callbackArgs Any If the client supplied this field in the initial request, it is included in the response.
finished Boolean true if the request is complete and this is the last callback for the request; false if the client should expect additional callbacks. Required.
transactions Array An array of transaction data. Each element in this array corresponds to an element in the transactions array in the original request. However, the elements in this array may appear in a different order from those of the original request, and may contain only a subset of the transactions from the original request, e.g., because one provider responds more quickly than another. Required.

Each element of the transactions array is a JSON object with the following fields:

Field Type Description
transactionId String Client-supplied ID of this transaction as it appeared in the original request. Required.
transactionType String The string invoice. Required
statusType String One of pending, succeeded, or failed. Required
statusCode Integer Numeric code indicating the status of the transaction. See the "Transaction Status Codes" section. Required.
statusDescription String Human-readable description of the status of the transaction. Required.
finished Boolean Boolean value indicating whether this transaction is now finished (either successfully or not as indicated by statusCode). No further updates for a finished transaction will be sent. Required.
subscriberAccountId String The provider-assigned account ID of the party from whom payment was requested.
provider String The Segovia-assigned ID of the payment provider, e.g., safaricom-kenya. This field will be present unless autodetection was requested but wasn't successful.
collectionAccountId String Segovia's collection account number on this transaction's payment provider, if provider is present.
reference String The Segovia-generated reference code for this invoice.
amountRequested Decimal The amount requested by the client in the original invoice.
currencyRequested String ISO 4217 currency code of the amount requested.
invoiceFeePaid Decimal The amount of money charged to send the invoice request.
invoiceFeeCurrency Decimal ISO 4217 currency code of the invoice fee amount.
amountPaid Decimal The amount actually paid by the end user, if a payment corresponding to this invoice has been received by the gateway. Does not account for Segovia's fees. May not equal the requested amount.
currencyPaid String ISO 4217 currency code of the amount paid.
feePaid Decimal The amount of money charged to handle the incoming payment. This will only be present if the gateway has received an incoming payment corresponding to this invoice.
feeCurrency String ISO 4217 currency code of the collection fee amount, if the gateway has received an incoming payment corresponding to this invoice.
walletUpdate Object A JSON object describing the effect on the wallet balance, if the gateway has received an incoming payment corresponding to this invoice.
datePaid String If it can be determined, the date (and possibly time) the payment was actually made. ISO-8601 format, e.g., 2018-01-01T12:34:56.789Z. Not available on all providers.

The walletUpdate object has the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields. See the Wallets page for information about how wallets work.

Field Type Description
walletId String The ID of the affected wallet or subwallet, if any. Required.
walletCurrency String ISO 4217 currency code of the wallet's balance. Required.
startingCurrentBalance Decimal The current balance of the wallet or subwallet before the payment was applied. Required.
endingCurrentBalance Decimal The current balance of the wallet or subwallet after the payment was applied. Required.

/api/collect/prefix/list

Lists the reference code prefixes currently assigned to a client. This is a synchronous request; results are returned in the HTTPS response.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
provider String Payment provider whose prefixes should be listed. If not supplied, all prefixes on all providers are listed.
clientCustomerId String List prefixes associated with this customer. If not supplied, prefixes are listed without regard to their customer IDs.

Response Fields

Field Type Description
clientId String The client ID specified in the request. Required.
requestId String Client-generated unique identifier for this request, the same value that was included in the original request. Required.
prefixes Array The results of the query. May be empty if there are no prefixes to list. Required.

Each element of the prefixes array has the following fields.

Field Type Description
prefix String The reference code prefix. Required.
provider String Segovia-assigned ID of the payment provider on which the prefix is valid. Required.
clientCustomerId String If this prefix is associated with a particular customer, its ID.

/api/collect/test

Simulates a collection. This causes a new collection transaction to be generated and delivered to the client using the same mechanisms as a real incoming payment from a subscriber, including collection confirmation callbacks.

Unlike a real collection, the collection generated by this API request will always come from the test payment provider and will always be routed to the client that made this request, regardless of the value of the reference code.

This request itself is synchronous and its success is indicated in the HTTPS response. However, the collection is created asynchronously and may cause the gateway to send notification callback requests to the client.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
notificationCallbackUrl String The URL to send collection notification callback requests to. If not set, the URL configured for the client, if any, is used. If no URL is specified for the client, no notification callbacks are sent for this collection.
collectionConfirmationUrl String The URL to send collection confirmation callback requests to. If not set, the URL configured for the client, if any, is used. If no URL is specified for the client, no confirmation callback is sent for this collection.
amount Decimal The amount to simulate receiving. Required.
currency String ISO 4217 currency code of the simulated payment. Required.
subscriberAccountId String This is copied verbatim to the collection transaction's subscriberAccountId field if present. If not present, the gateway will provide a default value.
name String This is copied verbatim to the collection transaction's name field if present. If not present, the collection transaction will not include a subscriber name.
reference String This is copied verbatim to the collection transaction's reference field if present. If not present, the gateway will provide a default value. When testing, it is a good idea to use a value that starts with a reference prefix you're likely to use on a real payment provider. See Collections for more information about reference codes and prefixes.

Response Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String The client ID specified in the request. Required.
requestId String Client-generated unique identifier for this request, the same value that was included in the original request. Required.
statusType String One of succeeded or failed. Required.
statusCode Integer Numeric code indicating the result of the request. See the "Transaction Status Codes" section. Required.
statusDescription String A human-readable description of the result of the request. Required.
transactionId String If the collection was successfully created, the transaction ID it was assigned.

/api/lookup

Looks up the names of a list of recipients. Not all providers are supported; if a lookup request for an unsupported provider is sent, a 320 Operation Not Supported By Provider will be returned.

It is possible to get a failure status in a response that nonetheless includes a value in the name field. If the payment gateway has a name on record for a given recipient account from a previous transaction, that name will be returned even if the provider doesn't support on-demand name lookups. The nameTimestamp field indicates when a name was supplied by the payment provider. Applications can examine that value if they want to discard names that were looked up too long ago and are potentially stale; what age should be considered "stale" depends on the specific needs of each application.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
callbackArgs Any Passed back to the client when the gateway transmits results.
callbackUrl String The URL to send callback requests to. May be up to 200 characters long. Ignored if a callback URL is configured for the client.
batchReference String An identifier for this batch. Not required to be unique.
transactions Array The lookups to process. Required.

Each element of the lookups array has the following fields.

Field Type Description
transactionId String A client-generated unique identifier for this transaction. Transaction IDs must be unique across all requests from a client regardless of request type. Required.
provider String The Segovia-assigned ID of the payment provider, e.g., mtn-rwanda, or autodetect to attempt to automatically detect the provider based on the recipient account ID. Required.
recipientAccountId String The provider-assigned ID of the recipient, e.g., a phone number in the case of mobile money providers. Required.
retryWindowSeconds Integer Time period (in seconds) during which the payment gateway will continue to retry requests that fail due to a transient error from the payment provider. If this field isn't present, a default value of 14400 seconds (4 hours) is used. If this field is set to 0, retries are disabled entirely, meaning that the payment gateway will not re-attempt the request if the initial attempt fails.
otherParams Object Any additional parameters required by the payment provider and not covered by the fields above. Shouldn't be needed in most cases.

Callback Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String The client ID specified in the request. Required.
requestId String Client-generated unique identifier for this request, the same value that was included in the original request. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
callbackArgs Any If the client supplied this field in the initial request, it is included in the response.
finished Boolean true if the request is complete and this is the last callback for the request; false if the client should expect additional callbacks. Required.
transactions Array An array of lookup data. Each element in this array corresponds to an element in the lookups array in the original request. However, the elements in this array may appear in a different order from those of the original request, and may contain only a subset of the transactions from the original request, e.g., because one provider responds more quickly than another. Required.

Each element of the transactions array is a JSON object with the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
transactionId String Client-supplied ID of this transaction as it appeared in the original request. Required.
transactionType String The string lookup. Required
statusType String One of pending, succeeded, or failed. Required
statusCode Integer Numeric code indicating the status of the transaction. See the "Transaction Status Codes" section. Required.
statusDescription String Human-readable description of the status of the transaction. Required.
finished Boolean Boolean value indicating whether this transaction is now finished (either successfully or not as indicated by statusCode). No further updates for a finished transaction will be sent. Required.
providerTransactionId String The provider-generated ID for this transaction, if any.
name String If available, the name of the recipient as reported by the provider. Not all providers supply recipient names to the gateway.
nameTimestamp String The date and time name was received from the provider in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.SSSZ). Some providers only supply recipient names to the gateway some time after a payment has completed, in which case name might be a value from an earlier payment. The client can use the timestamp if it wants to treat names as stale if they were reported more than a certain amount of time in the past.

/api/pay

Initiates payments to some number of recipients.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
callbackArgs Any Passed back to the client when the gateway transmits results.
callbackUrl String The URL to send callback requests to. May be up to 200 characters long. Ignored if a callback URL is configured for the client.
batchReference String An identifier for this batch. Not required to be unique.
transactions Array The transactions to process. Required.

Each element of the transactions array is a JSON object with the following fields. This is identical to the transaction structure of the /api/validate request except that some fields which are optional in those requests are required here.

Field Type Description
transactionId String A client-generated unique identifier for this transaction. Transaction IDs must be unique across all requests from a client regardless of request type. Required.
provider String The Segovia-assigned ID of the payment provider, e.g., mtn-rwanda, or autodetect to attempt to automatically detect the provider based on the recipient account ID. Required.
recipientAccountId String The provider-assigned ID of the recipient. For mobile money payments, this should be the recipient's mobile number including country code. Required.
amount Decimal The amount of money to transfer to the recipient. Required.
currency String ISO 4217 currency code. Required.
name String The recipient’s full name. This name will be screened against national and intergovernmental financial sanctions lists in accordance with our compliance policy. Required.
reference String An identifier for this transaction. Not required to be unique. Recipients will not see this.
recipientId String A unique identifier for this recipient.
clientCustomerId String If the request is being made on behalf of a customer of the client, that customer's unique ID.
reason String A convenient description of this particular transfer. This note may be sent to recipients as part of the payment confirmation if supported by the payment provider (e.g. in the body of a confirmation SMS).
nameParts Array An array of individual name parts. May contain empty strings as elements to maintain consistency across recipients, e.g., if a country’s name format is "First Middle Last" and someone has no middle name, this could be, ["John", "", "Smith"]. If not present and the payment provider requires names to be split into separate parts, the gateway will attempt to parse the value of name.
trusteeName String The name of a person or organization who will accept the funds on the recipient’s behalf. This name will be screened against national and intergovernmental financial sanctions lists in accordance with our compliance policy.
aliases Array Additional names that the recipient or trustee is known by. These names will be screened against national and intergovernmental financial sanctions lists in accordance with our compliance policy.
phone String The recipient’s telephone number.
address String The recipient’s street address or post office box number.
address2 String Additional information about the recipient’s street address.
city String The recipient’s city or town.
province String The recipient’s province or state.
postalCode String The recipient’s postal code.
country String The recipient’s two-letter ISO-3166-1 country code.
birthDate String The recipient’s birthdate in ISO-8601 (YYYY-MM-DD) format.
walletId String Which wallet or subwallet to use for this payment. Be aware that wallets are often tied to payment providers; specifying a wallet ID that isn't valid for this payment's provider will result in an error. If this field isn't present, the payment gateway will select the appropriate main wallet for the payment provider.
retryWindowSeconds Integer Time period (in seconds) during which the payment gateway will continue to retry payments that fail due to a transient error from the payment provider. If this field isn't present, a default value of 14400 seconds (4 hours) is used. If this field is set to 0, retries are disabled entirely, meaning that the payment gateway will not re-attempt payment transmission if the initial attempt fails.
sender Object Personal details of the individual sending the payment.
otherParams Object Any additional parameters required by the payment provider and not covered by the fields above. Shouldn't be needed in most cases.

The optional sender field inside a transaction object contains an object with the following fields.

Field Type Description
customerIdentificationNumber String A client-assigned identifier for this individual sender. For example, if you have a unique user ID for each sender in your application, you can use that user ID as the value for this field. If you ever need to request individual sender data that you've transmitted to the gateway, this identifier will be used to look up the relevant sender details. Required.
accountNumber String The sender's account number associated with this payment. This should be a unique identifier that will enable you to associate a payment with that individual. If your system doesn't have the notion of an account number that's distinct from a customer identification number, you may use the same value as the customerIdentificationNumber field. Required.
name String The sender's full name. Required.
address String The sender's street address or post office box number.
address2 String Additional information about the sender's street address.
city String The sender's city or town.
province String The sender's province or state.
postalCode String The sender's postal code.
country String The sender's two-letter ISO-3166-1 country code.
birthDate String The sender's birthdate in ISO-8601 (YYYY-MM-DD) format.
phone String The sender's telephone number including country code.

Callback Fields

The callback request contains the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String The client ID specified in the request. Required.
requestId String Client-generated unique identifier for this request, the same value that was included in the original request. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
callbackArgs Any If the client supplied this field in the initial request, it is included in the response.
finished Boolean true if the request is complete and this is the last callback for the request; false if the client should expect additional callbacks. Required.
transactions Array An array of transaction data. Each element in this array corresponds to an element in the transactions array in the original request. However, the elements in this array may appear in a different order from those of the original request, and may contain only a subset of the transactions from the original request, e.g., because one provider responds more quickly than another. Required.

Each element of the transactions array is a JSON object with the following fields:

Field Type Description
transactionId String Client-supplied ID of this transaction as it appeared in the original request. Required.
transactionType String The string pay. Required
statusType String One of pending, succeeded, or failed. Required
statusCode Integer Numeric code indicating the status of the transaction. See the "Transaction Status Codes" section. Required.
statusDescription String Human-readable description of the status of the transaction. Required.
finished Boolean Boolean value indicating whether this transaction is now finished (either successfully or not as indicated by statusCode). No further updates for a finished transaction will be sent. Required.
provider String The Segovia-assigned ID of the payment provider, e.g., mtn-rwanda. This field will be present unless autodetection was requested but wasn't successful.
providerTransactionId String The provider-generated ID for this transaction, if any.
amountPaid Decimal The amount actually paid. May be less than the requested amount for some providers, e.g., if the provider imposes limits on maximum amounts.
currency String ISO 4217 currency code of the amount paid. This field will be present if the payment succeeded.
feePaid Decimal The amount of money charged to process the transaction. This is not included in amountPaid; that is, the total amount debited from the payer account is amountPaid + feePaid.
feeCurrency String ISO 4217 currency code of the fee amount.
datePaid String If it can be determined, the date (and possibly time) the payment was actually made. ISO-8601 format, e.g., 2018-01-01T12:34:56.789Z. Not available on all providers.
name String If available, the name of the recipient as reported by the provider. Not all providers supply recipient names to the gateway.
nameTimestamp String The date and time name was received from the provider in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.SSSZ). Some providers only supply recipient names to the gateway some time after a payment has completed, in which case name might be a value from an earlier payment. The client can use the timestamp if it wants to treat names as stale if they were reported more than a certain amount of time in the past.
redemptionCode String Code or password the recipient needs to present to collect the payment, if required by payment provider.
walletUpdate Object If the payment succeeded, a JSON object describing the effect on the wallet balance.

The walletUpdate object has the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields. See the Wallets page for information about how wallets work.

Field Type Description
walletId String The ID of the affected wallet or subwallet, if any. Required.
walletCurrency String ISO 4217 currency code of the wallet's balance. Required.
startingCurrentBalance Decimal The current balance of the wallet or subwallet before the payment was applied. Required.
endingCurrentBalance Decimal The current balance of the wallet or subwallet after the payment was applied. Required.

/api/paymentproviders

Returns a list of the client's supported payment providers, along with any currency restrictions they have. This call always returns its results immediately, in the HTTPS response, and does not generate callbacks.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.

Response Fields

Field Type Description
clientId String Identifies the client. Required.
paymentProviders Array An array of payment provider information. Required.

Each entry in the paymentProviders array may contain the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
name String The Segovia-assigned ID of the payment provider, e.g. mtn-rwanda. This can be used as the provider ID in calls to /api/pay and /api/validate. Required.
supportedCurrencies Array If present, this field contains a list of ISO 4217 currency codes as strings. These are the only currencies that this payment provider supports. If this field is not present, the payment provider has no currency restrictions.

/api/reverse

Requests reversal (refund) of a previously completed transaction. Reversal frequently requires the payment provider to manually review the request, so this can take a while to complete. Reversals are typically at the discretion of the payment provider and not all transactions may be reversed.

If successful, the amount reversed (minus any applicable fees) is credited to the same wallet or subwallet that the original payment was made from, unless the payment came from a subwallet that is now deactivated. In that case, the reversal is credited to the main wallet.

A reversal request is itself a transaction and its progress is reported using the same mechanisms (callbacks and/or polling /api/transactionstatus) as other kinds of transactions.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
callbackArgs Any Passed back to the client when the gateway transmits results.
callbackUrl String The URL to send callback requests to. May be up to 200 characters long. Ignored if a callback URL is configured for the client.
transactions Array An array of reversal request objects. Required.

Each element of the transactions array is a JSON object with the following fields:

Field Type Description
transactionId String A client-generated unique identifier for this transaction. Transaction IDs must be unique across all requests from a client regardless of request type. This is the ID of the reversal. Required.
transactionIdToReverse String The ID of the original successful transaction that should be reversed. Required.
reason String A human-readable description of the reason for the reversal. This will be transmitted to the payment provider and may be helpful if the provider reviews reversal requests manually.

Callback Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String The client ID specified in the request. Required.
requestId String Client-generated unique identifier for this request, the same value that was included in the original request. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
callbackArgs Any If the client supplied this field in the initial request, it is included in the response.
finished Boolean true if the request is complete and this is the last callback for the request; false if the client should expect additional callbacks. Required.
transactions Array An array of JSON objects describing the results of the operation. Required.

Each element of the transactions array is a JSON object with the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
transactionId String The ID of the reversal transaction. Required.
transactionType String The string reverse. Required
transactionIdToReverse String The ID of the transaction whose reversal was requested. Required.
statusType String One of pending, succeeded, or failed. This refers to the status of the reversal, not the original transaction. Required
statusCode Integer Numeric code indicating the current status of the reversal. See the "Transaction Status Codes" section. This refers to the status of the reversal, not the original transaction. Required.
statusDescription String A human-readable description of the current status of the reversal. Required.
finished Boolean A boolean value indicating whether this reversal is now finished (either successfully or not as indicated by statusCode). No further updates for a finished reversal will be sent. Required.
provider String The Segovia-assigned ID of the payment provider, e.g., mtn-rwanda, or autodetect when autodetection was requested but wasn't successful.
reversedAmount Decimal If the reversal was successful, the amount of money that was returned. This may be less than the amount of the original transaction.
reversedCurrency String ISO 4217 currency code of the amount of the reversal, if successful.
feePaid Decimal Amount of the fee paid to process the reversal, if any.
feeCurrency String ISO 4217 currency code of the fee amount.
providerTransactionId String The provider-generated ID for this reversal, if any.
reason String If available, a human-readable reason for the result of the reversal.
reversedTime String If available, the date and time the provider indicated the reversal was completed, in ISO-8601 complete date and time format (YYYY-MM-DDThh:mm:ssZ). Not all providers indicate the time of completion of reversals.
walletUpdate Object If the reversal succeeded, a JSON object describing the effect on the wallet balance.

The walletUpdate object has the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields. See the Wallets page for information about how wallets work.

Field Type Description
walletId String The ID of the affected wallet or subwallet. Required.
walletCurrency String ISO 4217 currency code of the wallet's balance. Required.
startingCurrentBalance Decimal The current balance of the wallet before the reversal was applied. Required.
endingCurrentBalance Decimal The current balance of the wallet after the reversal was applied. Required.

/api/sms/send

Initiates sending SMS messages to some number of recipients.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
callbackArgs Any Passed back to the client when the gateway transmits results.
callbackUrl String The URL to send callback requests to. May be up to 200 characters long. Ignored if a callback URL is configured for the client.
transactions Array The transactions to process. Required.

Each element of the transactions array is a JSON object with the following fields.

Field Type Description
transactionId String A client-generated unique identifier for this transaction. Transaction IDs must be unique across all requests from a client regardless of request type. Required.
recipientAccountId String The recipient’s telephone number, including country code. Required.
message String The message to be sent to the recipient. Maximum message length 140 characters. Required.
walletId String Which wallet or subwallet to use for this SMS request. Required.
provider String Which provider to use to send the SMS. In most cases, this shouldn't be specified; the gateway will choose a provider based on the recipient's telephone number. But this may be set to test to simulate SMS requests without actually sending messages.
shortcode String The short code to use as the sender of the SMS. Using a custom short code requires account setup; contact your Segovia account representative.
relatedTransactionId String The ID of the transaction that this SMS request is related to. Must be a transaction ID of a request that has already been sent to the gateway.
retryWindowSeconds Integer Time period (in seconds) during which the payment gateway will continue to retry requests that fail due to a transient error from the provider. If this field isn't present, a default value of 14400 seconds (4 hours) is used. If this field is set to 0, retries are disabled entirely, meaning that the payment gateway will not re-attempt the request if the initial attempt fails.
otherParams Object Any additional parameters required by the SMS service provider and not covered by the fields above. Shouldn't be needed in most cases.

Callback Fields

The callback request contains the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String The client ID specified in the request. Required.
requestId String Client-generated unique identifier for this request, the same value that was included in the original request. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
callbackArgs Any If the client supplied this field in the initial request, it is included in the response.
finished Boolean true if the request is complete and this is the last callback for the request; false if the client should expect additional callbacks. Required.
transactions Array An array of transaction data. Each element in this array corresponds to an element in the transactions array in the original request. However, the elements in this array may appear in a different order from those of the original request, and may contain only a subset of the transactions from the original request, e.g., because one provider responds more quickly than another. Required.

Each element of the transactions array is a JSON object with the following fields:

Field Type Description
transactionId String Client-supplied ID of this transaction as it appeared in the original request. Required.
transactionType String The string sms-send. Required
statusType String One of pending, succeeded, or failed. Required
statusCode Integer Numeric code indicating the status of the transaction. See the "Transaction Status Codes" section. Required.
statusDescription String Human-readable description of the status of the transaction. Required.
finished Boolean Boolean value indicating whether this transaction is now finished (either successfully or not as indicated by statusCode). No further updates for a finished transaction will be sent. Required.
feePaid Decimal The amount of money charged to process the transaction. This is not included in amountPaid; that is, the total amount debited from the payer account is amountPaid + feePaid.
feeCurrency String ISO 4217 currency code of the fee amount.
timeReceived String If indicated by the SMS service provider, the timestamp the SMS message was actually received, in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ).
walletUpdate Object If the SMS message was successfully sent, a JSON object describing the effect on the wallet balance.

The walletUpdate object has the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields. See the Wallets page for information about how wallets work.

Field Type Description
walletId String The ID of the affected wallet or subwallet, if any. Required.
walletCurrency String ISO 4217 currency code of the wallet's balance. Required.
startingCurrentBalance Decimal The current balance of the wallet or subwallet before the payment was applied. Required.
endingCurrentBalance Decimal The current balance of the wallet or subwallet after the payment was applied. Required.

/api/subwallet/activate

Activates a subwallet that was previously deactivated. See the Wallets page for information about how subwallets work. If the wallet is already activated, this request has no effect and returns a success status code.

This request is synchronous; the gateway returns results directly in the HTTPS response rather than using callbacks.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
walletId String The ID of the subwallet to activate, in path form main-wallet-name/subwallet-name. Required.

Response Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String The client ID specified in the request. Required.
requestId String Client-generated unique identifier for this request, the same value that was included in the original request. Required.
statusType String One of succeeded or failed. Required.
statusCode Integer Numeric code indicating the result of the request. See the "Transaction Status Codes" section. Required.
statusDescription String A human-readable description of the result of the request. Required.

/api/subwallet/create

Creates a new subwallet associated with an existing wallet. See the Wallets page for information about how subwallets work.

This request is synchronous; the gateway returns results directly in the HTTPS response rather than using callbacks.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
walletId String The ID of the subwallet to create, in path form main-wallet-name/subwallet-name. Required.

Response Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String The client ID specified in the request. Required.
requestId String Client-generated unique identifier for this request, the same value that was included in the original request. Required.
statusType String One of succeeded or failed. Required.
statusCode Integer Numeric code indicating the result of the request. See the "Transaction Status Codes" section. Required.
statusDescription String A human-readable description of the result of the request. Required.

/api/subwallet/deactivate

Deactivates a subwallet. See the Wallets page for information about how subwallets work. If the wallet is already deactivated, this request has no effect and returns a success status code.

This request is synchronous; the gateway returns results directly in the HTTPS response rather than using callbacks.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
walletId String The ID of the subwallet to deactivate, in path form main-wallet-name/subwallet-name. Required.

Response Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String The client ID specified in the request. Required.
requestId String Client-generated unique identifier for this request, the same value that was included in the original request. Required.
statusType String One of succeeded or failed. Required.
statusCode Integer Numeric code indicating the result of the request. See the "Transaction Status Codes" section. Required.
statusDescription String A human-readable description of the result of the request. Required.

/api/subwallet/transfer

Moves funds between subwallets of the same main wallet or between a subwallet and its main wallet. See the Wallets page for information about how subwallets work.

It is not permitted to transfer funds between different main wallets; if you need to do this, please contact Segovia support.

This request is synchronous; the gateway returns results directly in the HTTPS response rather than using callbacks. If a large enough number of transfers is requested that the gateway is unable to process them all in a reasonable amount of time, the response may indicate that some of the transfers are still pending; in that case the statuses may be queried later using /api/transactionstatus.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
transactions Array A list of subwallet transfer operations to perform. Required.

Each element of the transactions array is a JSON object with the following fields.

Field Type Description
transactionId String A client-generated unique identifier for this transaction. Transaction IDs must be unique across all requests from a client regardless of request type. Required.
fromWalletId String Identifier of the originating wallet or subwallet, from which funds will be transferred. Required.
toWalletId String Identifier of the receiving wallet or subwallet, to which funds will be transferred. Required.
amount Decimal Amount of money to move. Must be a positive number. Required.
currency String ISO 4217 currency code for the amount to move. At present, this must always be equal to the wallet's currency. Required.

Response Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String The client ID specified in the request. Required.
requestId String Client-generated unique identifier for this request, the same value that was included in the original request. Required.
transactions Array An array of transaction data. Each element in this array corresponds to an element in the transactions array in the original request. However, the elements in this array may appear in a different order from those of the original request. Required.

Each element of the transactions array is a JSON object with the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
transactionId String Client-supplied ID of this transaction as it appeared in the original request. Required.
transactionType String The string subwalletTransfer. Required.
statusType String One of pending, succeeded, or failed. Required.
statusCode Integer Numeric code indicating the result of the request. See the "Transaction Status Codes" section. Required.
statusDescription String A human-readable description of the result of the request. Required.
fromWalletUpdate Object If the request succeeded, a JSON object describing the effect on the balance of the originating wallet or subwallet.
toWalletUpdate Object If the request succeeded, a JSON object describing the effect on the balance of the receiving wallet or subwallet.

The fromWalletUpdate and toWalletUpdate objects have the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields. See the Wallets page for information about how wallets work.

Field Type Description
walletId String The ID of the affected wallet or subwallet, if any. Required.
walletCurrency String ISO 4217 currency code of the wallet's balance. Required.
startingCurrentBalance Decimal The current balance of the wallet or subwallet before the funds were moved. Required.
endingCurrentBalance Decimal The current balance of the wallet or subwallet after the funds were moved. Required.

/api/transactionstatus

Queries the status of transactions. This request is synchronous; the gateway returns results directly in the HTTPS response rather than using callbacks.

This is most often used in cases where the client can't receive callback requests from the gateway for whatever reason. Callbacks are generally the preferable approach when possible.

A few examples:

The results are sorted by the time the payment gateway started processing the transactions unless useUpdatedTime is true, in which case they are sorted by the time of the most recent status change.

Input Fields

Field Type Description Default
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
startTime String Search for transactions whose time (as directed by useUpdatedTime) is at or after a specific time. This must be a timestamp in ISO-8601 complete date and time format (YYYY-MM-DDThh:mm:ssZ). Current time minus 30 days unless transactionIds or originalRequestIds is nonempty, in which case no start time filter is applied by default
endTime String Search for transactions whose time (as directed by useUpdatedTime) is before a specific time. This must be a timestamp in ISO-8601 complete date and time format (YYYY-MM-DDThh:mm:ssZ). startTime plus 30 days unless transactionIds or originalRequestIds is nonempty, in which case no end time filter is applied by default
useUpdatedTime Boolean If true, transactions are matched and sorted based on the time of the most recent status update. If false, transactions are matched and sorted based on the time the gateway started processing them, usually the right choice unless you're polling for updates on long-running transactions. false
sinceTransactionId String Search for transactions that would appear after the specified ID in search results. Results are sorted by time according to the value of the useUpdatedTime field. Combined with maxResults, this may be used to page through a large result set. It may also be used to poll for newly-arrived collection or reversal transactions. Start with the first transaction that matches the other search criteria
providers Array Limit results to transactions from specific payment providers. This is an array of strings, each of which must be the Segovia-assigned ID of a provider, e.g., mtn-rwanda.
statusCodes Array Limit results to transactions with specific status codes. This is a list of integers, each of which must be a valid status code as defined in the "Transaction Status Codes" section of this documentation.
statusTypes Array Limit results to transactions of specific status types. This is a list of strings, each of which must be one of pending, succeeded, or failed.
transactionTypes Array Limit results to transactions of specific types. This is an array of strings, each of which must be one of collect, lookup, pay, reverse, or validate. collect, lookup, pay, reverse, validate
originalRequestIds Array Search for transactions that were sent to the payment gateway in specific API requests. This is an array of strings as supplied by the client in the requestId fields of previous requests. If search criteria are specified, they act as filters on the list of transactions in these requests. If this is specified, the results will not be filtered by time by default, so you can use this to fetch the statuses of a particular request's transactions without needing to know when it was sent.
transactionIds Array An array of string transaction IDs, either as supplied by the client in earlier API requests or as generated by the gateway for non-client-initiated operations. If search criteria are specified, they act as filters on this list of transactions.
maxResults Integer Limit the results to a certain number of transactions. Maximum allowed value is 10000; larger values will be ignored. 10000

Response Fields

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
transactions Array An array of objects with information about the requested transactions. Required.
finished Boolean If true, this response contains results for all transactions matching the search criteria. If false, this response contains the number of results specified in the maxResults field of the request, but there are additional transactions matching the criteria. Required.

Each element in the transactions array has the same fields as would be present in a callback request for the transaction. Since this can vary depending on the specific type of transaction, the full set of field combinations isn’t listed here (refer to the callback formats for the API requests that initiate new transactions) but each entry in the array will contain the following fields which are present in the callbacks for all transactions:

Field Type Description
transactionId String Client-supplied ID of this transaction as it appeared in the original request. Required.
transactionType String One of collect, invoice, lookup, pay, reverse, sendSms, subwalletTransfer, or validate for transactions that exist, or null if the request specified a nonexistent transaction ID. Additional types may be added later. Required.
statusType String One of pending, succeeded, or failed. Required
statusCode Integer Numeric code indicating the status of the transaction. See the "Transaction Status Codes" section. Required.
statusDescription String Human-readable description of the status of the transaction. Required.
finished Boolean Boolean value indicating whether this transaction is now finished (either successfully or not as indicated by statusCode). No further updates for a finished transaction will be sent. Required.
provider String The Segovia-assigned ID of the payment provider, e.g., mtn-rwanda. This field will be present unless autodetection was requested but wasn't successful.

In addition, the following may be present:

Field Type Description
relatedTransactionIds Array If subsequent transactions are related to this one, an array of their transaction IDs. Currently the only transactions that can appear here are reversal requests. To find out the status of the related transactions, query them by ID.

/api/validate

Validates a list of proposed transactions. Will check if the recipient account passes screening. May verify that information about recipients is accurate, and return corrected information when available from the underlying payment provider. May confirm that there is money available to cover the requested payments. The specific validation steps will vary depending on the capabilities of the provider.

Input Fields

Field Type Description
clientId String Identifies the client. Required.
requestId String Client-generated unique identifier for this request. Required.
callbackArgs Any Passed back to the client when the gateway transmits results.
callbackUrl String The URL to send callback requests to. May be up to 200 characters long. Ignored if a callback URL is configured for the client.
batchReference String An identifier for this batch. Not required to be unique.
transactions Array The transactions to process. A "transaction" here refers to verifying a recipient’s information, not transferring money. Required.

Each element of the transactions array has the following fields. This is identical to the transaction structure of the /api/pay request except that some fields which are required in that request are optional here.

Field Type Description
transactionId String A client-generated unique identifier for this transaction. Transaction IDs must be unique across all requests from a client regardless of request type. Required.
provider String The Segovia-assigned ID of the payment provider, e.g., mtn-rwanda, or autodetect to attempt to automatically detect the provider based on the recipient account ID. Required.
recipientAccountId String The provider-assigned ID of the recipient, e.g., a phone number in the case of mobile money providers. Required.
name String The recipient’s full name. This name will be screened against national and intergovernmental financial sanctions lists in accordance with our compliance policy. Required.
amount Decimal The amount of money to transfer to the recipient.
currency String ISO 4217 currency code.
payerAccountId String The ID of the account that will act as the source of the payment.
reference String An identifier for this transaction. Not required to be unique. Recipients will not see this.
recipientId String A unique identifier for this recipient.
clientCustomerId String If the request is being made on behalf of a customer of the client, that customer's unique ID.
walletId String Which wallet or subwallet to validate against. Be aware that wallets are often tied to payment providers; specifying a wallet ID that isn't valid for this validation request's provider will result in an error. If this field isn't present, the payment gateway will select the appropriate main wallet for the payment provider.
reason String A convenient description of the proposed payment. This won't be sent to recipients on validate requests, but may be included to confirm that it would be accepted if sent as part of a payment request.
nameParts Array An array of individual name parts. May contain empty strings as elements to maintain consistency across recipients, e.g., if a country’s name format is "First Middle Last" and someone has no middle name, this could be, ["John", "", "Smith"]. If not present and the payment provider requires names to be split into separate parts, the gateway will attempt to parse the value of name.
trusteeName String The name of a person or organization who will accept the funds on the recipient’s behalf. This name will be screened against national and intergovernmental financial sanctions lists in accordance with our compliance policy.
aliases Array Additional names that the recipient or trustee is known by. These names will be screened against national and intergovernmental financial sanctions lists in accordance with our compliance policy.
phone String The recipient’s telephone number.
address String The recipient’s street address or post office box number.
address2 String Additional information about the recipient’s street address.
city String The recipient’s city or town.
province String The recipient’s province or state.
postalCode String The recipient’s postal code.
country String The recipient’s two-letter ISO-3166-1 country code.
birthDate String The recipient’s birthdate in ISO-8601 (YYYY-MM-DD) format.
sender Object Personal details of the individual sending the payment.
retryWindowSeconds Integer Time period (in seconds) during which the payment gateway will continue to retry requests that fail due to a transient error from the payment provider. If this field isn't present, a default value of 14400 seconds (4 hours) is used. If this field is set to 0, retries are disabled entirely, meaning that the payment gateway will not re-attempt the request if the initial attempt fails.
otherParams Object Any additional parameters required by the payment provider and not covered by the fields above. Shouldn't be needed in most cases.

The optional sender field inside a transaction object contains an object with the following fields.

Field Type Description
customerIdentificationNumber String A client-assigned identifier for this individual sender. For example, if you have a unique user ID for each sender in your application, you can use that user ID as the value for this field. If you ever need to request individual sender data that you've transmitted to the gateway, this identifier will be used to look up the relevant sender details. Required.
accountNumber String The sender's account number associated with the validation request. This should be a unique identifier that will enable you to associate a payment with that individual. If your system doesn't have the notion of an account number that's distinct from a customer identification number, you may use the same value as the customerIdentificationNumber field. Required.
name String The sender's full name. Required.
address String The sender's street address or post office box number.
address2 String Additional information about the sender's street address.
city String The sender's city or town.
province String The sender's province or state.
postalCode String The sender's postal code.
country String The sender's two-letter ISO-3166-1 country code.
birthDate String The sender's birthdate in ISO-8601 (YYYY-MM-DD) format.
phone String The sender's telephone number including country code.

Callback Fields

Field Type Description
clientId String The client ID specified in the request. Required.
requestId String Client-generated unique identifier for this request, the same value that was included in the original request. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
callbackArgs Any If the client supplied this field in the initial request, it is included in the response.
finished Boolean true if the request is complete and this is the last callback for the request; false if the client should expect additional callbacks. Required.
transactions Array An array of transaction data. Each element in this array corresponds to an element in the transactions array in the original request. However, the elements in this array may appear in a different order from those of the original request, and may contain only a subset of the transactions from the original request, e.g., because one provider responds more quickly than another. Required.

Each element of the transactions array is a JSON object with the following fields:

Field Type Description
transactionId String Client-supplied ID of this transaction as it appeared in the original request. Required.
transactionType String The string validate. Required
statusType String One of pending, succeeded, or failed. Required
statusCode Integer Numeric code indicating the status of the transaction. See the "Transaction Status Codes" section. Required.
statusDescription String Human-readable description of the status of the transaction. Required.
finished Boolean Boolean value indicating whether this transaction is now finished (either successfully or not as indicated by statusCode). No further updates for a finished transaction will be sent. Required.
provider String The Segovia-assigned ID of the payment provider, e.g., mtn-rwanda. This field will be present unless autodetection was requested but wasn't successful.
providerTransactionId String The provider-generated ID for this transaction, if any.
name String If available, the name of the recipient as reported by the provider. Not all providers supply recipient names to the gateway.
nameTimestamp String The date and time name was received from the provider in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.SSSZ). Some providers only supply recipient names to the gateway some time after a payment has completed, in which case name might be a value from an earlier payment. The client can use the timestamp if it wants to treat names as stale if they were reported more than a certain amount of time in the past.

Collection Confirmation Callbacks

Some payment providers support confirmation of collections, such that the client has an opportunity to accept or reject a pending incoming payment. For such collections, the payment gateway can expose that ability to the client via a collection confirmation callback. This is usually used to reject payments whose reference codes aren't recognized, e.g., because a subscriber entered the wrong code.

The collection confirmation callback URL can be configured in the payment gateway user interface.

Collection confirmation callbacks are not retried since payment providers typically offer only a very short time window to reject a collection. If a collection confirmation callback can't be completed, the gateway assumes that the payment is legitimate and credits it to the client. This is also the behavior if no collection confirmation callback URL is configured.

Because providers only offer a very short time window to reject a collection, it's possible for a client to reject a collection but for the collection to succeed before the gateway has had time to deliver the rejection to the provider. In most cases this won't happen, but your application should be prepared to deal with a collection succeeding after it has been rejected.

Not all incoming payments will cause collection confirmation callback requests to be issued; some payment providers don't support the functionality, and some payment providers only support it on a subset of transactions. Your application should not assume that it will always get a collection confirmation callback request.

Request Fields

The body of the POST request to the client is a JSON-formatted data structure. As with requests from the client to the gateway, these requests include an Authorization HTTP header line with scheme Segovia and a signature parameter whose value is a hexadecimal representation of the HMAC-SHA256 digest of the request body using the secret key for callback requests from the gateway. The signature acts as evidence that the request really comes from the gateway. See the "Request Signature" section for more details on signatures.

Additional fields may be added over time; clients should ignore any unrecognized fields. A collection confirmation callback contains exactly one transaction.

Field Type Description
clientId String Identifies the client. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
transactionId String A gateway-assigned UUID for this payment. Required.
transactionType String The value collect. Required.
provider String Which payment provider this payment came from. This is a Segovia-assigned provider name, e.g., vodacom-tanzania. Required.
subscriberAccountId String The account ID of the party that initiated the payment. For mobile payments, this will be the subscriber's mobile number including country code. Required.
amountPaid Decimal The amount of money paid by the subscriber, not counting Segovia's fees. Required.
currency String The ISO 4217 code of the payment's currency.
datePaid String If it can be determined, the date (and possibly time) the payment was actually made. ISO-8601 format, e.g., 2018-01-01T12:34:56.789Z. Not available on all providers.
name String The name of the party that initiated the payment, if supplied by the payment provider.
reference String The reference code or payment identifier supplied by the party that initiated the payment, if applicable for the payment method.
providerTransactionId String The ID of this transaction in the payment provider's system, if available.

Response

The client should return a JSON-formatted data structure in its HTTP response to the gateway's request:

Field Type Description
confirmed Boolean True if the collection is confirmed to be valid and should be processed. Required.
message String Human-readable details about the confirmation or the rejection.

If the client returns an HTTP error response, the gateway will treat the collection as confirmed.

Collection Notification Callbacks

When incoming payments arrive and are successfully credited to the client, the payment gateway can send callback requests to inform the client about them. The callback URL can be configured in the payment gateway user interface.

The gateway will retry failed collection notification callbacks for no less than 3 days before giving up. If the client is unable to receive callback requests or no collection notification URL is configured, collection transactions can be found using /api/transactionstatus or in the transaction history in the user interface.

These callbacks are distinct from the collection confirmation callbacks described above; they are purely informational in nature and don't allow the client to accept or reject the collection transactions.

Request Fields

The body of the POST request to the client is a JSON-formatted data structure. As with requests from the client to the gateway, these requests include an Authorization HTTP header line with scheme Segovia and a signature parameter whose value is a hexadecimal representation of the HMAC-SHA256 digest of the request body using the secret key for callback requests from the gateway. The signature acts as evidence that the request really comes from the gateway. See the "Request Signature" section for more details on signatures.

Additional fields may be added over time; clients should ignore any unrecognized fields.

Field Type Description
clientId String Identifies the client. Required.
timestamp String Timestamp of callback in ISO-8601 complete date and time format with milliseconds (YYYY-MM-DDThh:mm:ss.sssZ). Required.
transactions Array The details of the collection. Required.

The transactions array has a single object with the following fields, which are also the fields returned by /api/transactionstatus for a collection transaction.

Field Type Description
transactionId String A gateway-assigned UUID for this payment. Required.
transactionType String The value collect. Required.
statusCode Integer The current status of the transaction. See the "Transaction Status Codes" section. This should always be 200. Required.
statusType String The value succeeded. Required.
statusDescription String A human-readable description of the transaction's status. Required.
finished Boolean The value true. Required.
provider String Which payment provider this payment came from. This is a Segovia-assigned provider name, e.g., vodacom-tanzania. Required.
subscriberAccountId String The account ID of the party that initiated the payment. For mobile payments, this will be the subscriber's mobile number including country code. Required.
amountPaid Decimal The amount of money paid by the subscriber, not counting Segovia's fees. Required.
currency String The ISO 4217 code of the payment's currency.
feePaid Decimal The amount of money deducted from the payment amount as fees.
feeCurrency String The ISO 4217 code of the currency in which fees were charged.
datePaid String If it can be determined, the date (and possibly time) the payment was actually made. ISO-8601 format, e.g., 2018-01-01T12:34:56.789Z. Not available on all providers.
name String The name of the party that initiated the payment, if supplied by the payment provider.
reference String The reference code or payment identifier supplied by the party that initiated the payment, if applicable for the payment method.
providerTransactionId String The ID of this transaction in the payment provider's system, if available.
walletUpdate Object Describes the payment's impact on the wallet balance.

The walletUpdate object has the following fields. Additional fields may be added over time; clients should ignore any unrecognized fields. See the Wallets page for information about how wallets work.

Field Type Description
walletId String The ID of the affected wallet or subwallet. Required.
walletCurrency String ISO 4217 currency code of the wallet's balance. Required.
startingCurrentBalance Decimal The current balance of the wallet before the payment was applied. Required.
endingCurrentBalance Decimal The current balance of the wallet after the payment was applied. Required.

Response

The client should return an HTTP 200 response. The response body is ignored by the gateway, but to minimize potential incompatibility with future API changes, an empty body is recommended.

If the client returns an HTTP error response, the gateway will retry the callback for up to 7 days.

Example Request Flow

From client:

POST /api/pay HTTP/1.1
Authorization: Segovia signature=(hmac-sha256 hex)
API-Version: 1.0
Host: payment-api.thesegovia.com
Content-Type: application/json; charset=UTF-8

{ "clientId": "example-client",
  "requestId": "aa67f1ab-ce1b-4a43-98c8-033228d2abad",
  "callbackArgs": {
    "reference": 29489213
  },
  "transactions": [
    { "transactionId": "27befd5b-d149-4c6f-91d4-5aa1e2e7c199",
      "provider": "mtn-rwanda",
      "recipientAccountId": "250789999999",
      "amount": 125,
      "currency": "RWF",
      "name": "Paul Niehaus" },
    { "transactionId": "77a191e5-72c0-4521-b377-f8df3b53d710",
      "provider": "airtel-ghana",
      "recipientAccountId": "233888888888",
      "amount": 240,
      "currency": "GHS",
      "name": "Michael Faye" }]}

Response from gateway:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=UTF-8

{ "message": "Request Received" }

Request from gateway with informational status update. One transaction has been sent to the payment provider and the other is queued to be sent.

POST /callback/result HTTP/1.1
Authorization: Segovia signature=(hmac-sha256 hex)
API-Version: 1.0
Content-Type: application/json; charset=UTF-8

{ "clientId": "example-client",
  "requestId": "aa67f1ab-ce1b-4a43-98c8-033228d2abad",
  "timestamp": "2016-03-12T14:52:26.418Z",
  "callbackArgs": {
    "reference": 29489213
  },
  transactions: [
    { "transactionId": "27befd5b-d149-4c6f-91d4-5aa1e2e7c199",
      "transactionType": "pay",
      "statusType": "pending",
      "statusCode": 110,
      "statusDescription": "Waiting for a response from the provider.",
      "finished": false },
    { "transactionId": "77a191e5-72c0-4521-b377-f8df3b53d710",
      "transactionType": "pay",
      "statusType": "pending",
      "statusCode": 100,
      "statusDescription": "The gateway has received the transaction.",
      "finished": false }]}

Response from client (body and content type are ignored):

HTTP/1.1 200 OK

Request from gateway with informational status update. The second transaction has been sent to the payment provider. Note the first transaction is not included here since its status hasn’t changed:

POST /callback/result HTTP/1.1
Authorization: Segovia signature=(hmac-sha256 hex)
API-Version: 1.0
Content-Type: application/json; charset=UTF-8

{ "clientId": "example-client",
  "requestId": "aa67f1ab-ce1b-4a43-98c8-033228d2abad",
  "timestamp": "2016-03-12T14:52:37.110Z",
  "callbackArgs": {
    "reference": 29489213
  },
  "results": [
    { "transactionId": "77a191e5-72c0-4521-b377-f8df3b53d710",
      "transactionType": "pay",
      "statusType": "pending",
      "statusCode": 110,
      "statusDescription": "Waiting for a response from the provider.",
      "finished": false }]}

Response from client (body and content type are ignored):

HTTP/1.1 200 OK

Request from gateway with final status updates for both transactions:

POST /callback/result HTTP/1.1
Authorization: Segovia signature=(hmac-sha256 hex)
API-Version: 1.0
Content-Type: application/json; charset=UTF-8

{ "clientId": "example-client",
  "requestId": "aa67f1ab-ce1b-4a43-98c8-033228d2abad",
  "timestamp": "2016-03-12T14:52:39.767Z",
  "callbackArgs": {
    "reference": 29489213
  },
  results: [
    { "transactionId": "27befd5b-d149-4c6f-91d4-5aa1e2e7c199",
      "transactionType": "pay",
      "amountPaid": 125,
      "currency": "RWF",
      "finished": true,
      "statusType": "succeeded",
      "statusCode": 200,
      "statusDescription": "Succeeded with provider transaction ID ABCDEFG",
      "providerTransactionId": "ABCDEFG",
      "feePaid": 5,
      "feeCurrency", "RWF",
      "datePaid": "2016-03-12T14:52:20.303Z"
    },
    { "transactionId": "77a191e5-72c0-4521-b377-f8df3b53d710",
      "transactionType": "pay",
      "finished": true,
      "statusType", "failed",
      "statusCode": 420,
      "statusDescription": "Recipient 233888888888 not found" }]}

Response from client (body and content type are ignored):

HTTP/1.1 200 OK

Transaction Status Codes

Transaction status is represented in three fields in the API.

statusType is a high-level categorization of the general state of the transaction. If all your application needs to know is whether a transaction is pending, successful, or failed, this field is all you need to examine.

statusCode is an enumerated integer value that contains more detail about what's going on with the transaction. The list of status codes is subject to future expansion, so if you're taking different actions based on specific conditions, it's a good idea to make sure your application falls back to reasonable default behaviors based on the status type. A given status code will always have the same status type.

statusDescription is a human-readable description of the transaction's status. In many cases this will simply be a description of the status code, but when there's additional relevant information (e.g., an error message from a payment provider) it may be included in the description.

As described earlier in this document, a transaction may progress through any number of informational statuses (e.g., "Transmitted," "Provider In Progress").

It is important to note that these status codes are returned as fields in JSON data structures, and there may be different status codes for different transactions listed in a single JSON structure. Although some transaction status codes are modeled after HTTP status codes, that should be considered a mnemonic aid only; these are not the HTTP response codes the gateway returns in response to client requests. See the "Example Request Flow" section for a demonstration of the distinction between HTTP response codes and transaction status codes.

Although some of the status codes for similar conditions have similar numeric values, your application should avoid assuming that certain numeric ranges of status codes have semantic meanings. Future additions to the list of status codes may violate that assumption.

Status Types

The statusType field may have one of the following values.

Value Description
pending The transaction is in progress. All informational status codes have this type.
succeeded The transaction was completed successfully.
failed The transaction failed or was rejected.

Pending Status Codes

Status codes with "pending" types indicate that the request is still ongoing (and thus the client can expect future results). A client may safely ignore all these status codes if it doesn't need to present progress information to a user. The gateway may issue any number of informational status updates, or none, over the course of handling a transaction if callbacks are enabled for the client or a callback URL was included in the request that initiated the transaction.

Note that there is no guarantee that status codes will be in a particular numeric range. Always look at the status type.

100 In Process

The gateway has received the transaction.

110 Transmitted

The transaction has been transmitted to the underlying provider and the gateway is awaiting a response.

115 Retransmitted

The gateway needed to retransmit the transaction, e.g., because the provider indicated there was a transient error.

119 Transmission Failed

The gateway failed to send the transaction to the provider, e.g., because of network connectivity problems, and will retry later. As with all 1xx status codes, no client action is required.

120 Provider In Progress

The provider has accepted, and has started processing, the transaction.

129 Provider Stalled

The provider has indicated that the transaction cannot be processed immediately, but the transaction is still queued for processing on the provider’s side.

140 Invoice Awaiting Acknowledgement

The gateway is waiting for the subscriber to acknowledge the invoice transaction.

141 Reply Received

The subscriber has replied to acknowledge the transaction.

142 Invoice Awaiting Payment

The subscriber has indicated that they will proceed with the transaction, but has not yet made payment.

150 Transaction Processed

The provider has indicated that it is finished processing the transaction, but has not yet returned final results to the gateway.

180 Status Unknown

The gateway is currently unable to determine the status of the transaction, e.g., because a payment provider failed to indicate whether or not the transaction succeeded. Depending on what happened, the gateway may be able to automatically determine the status at a later time. If this status persists, please contact Segovia support.

189 Rejected By Provider But Will Retry

The provider returned an error response indicating it was currently unable to process the transaction. The gateway will automatically retry the transaction.

190 Cancellation Requested

The gateway has been asked to cancel the transaction, but has not yet requested the cancellation from the provider.

191 Cancellation In Progress

The provider has been asked to cancel the transaction, but has not yet confirmed the cancellation.

199 Cancellation Rejected

The provider was unable to cancel the transaction; it will be processed as originally requested.

"Succeeded" Status Codes

Status codes with "succeeded" types indicate that a transaction completed as requested. A succeeded status code indicates that the gateway considers the transaction finished and will not send any subsequent results.

Note that there is no guarantee that status codes will be in a particular numeric range. Always look at the status type.

200 Complete

The transaction completed exactly as specified and there were no warnings from the provider.

201 Delivered

The transaction instructions have been delivered to the provider, but the provider does not have the ability to acknowledge successful receipt. The client may be able to verify delivery using some other method including manual intervention, but the gateway has taken the transaction as close to completion as it can. Most providers are able to confirm receipt, so in practice this status code should be rare.

230 Invoice Complete With Different Amount

The invoice transaction completed, but the amount paid by the subscriber was different from the amount originally requested.

"Failed" Status Codes

Status codes with "failed" types indicate that the transaction was unsuccessful. A failed code indicates that the gateway considers the transaction finished and will not send any subsequent results; the client must transmit a new transaction to the gateway if it wishes to retry the operation.

Note that there is no guarantee that status codes will be in a particular numeric range. Always look at the status type.

290 Cancelled

The transaction was successfully cancelled at the request of the client.

310 Recipient Information Mismatch

The supplied recipient information (name, address, etc.) did not match the provider’s records.

311 Missing Recipient Name

The transaction requires a recipient name, but none was provided.

312 Transaction Failed Screening

The transaction has failed Segovia's screening for blocked recipients. Please contact Segovia at api-support@thesegovia.com if you receive this error code and we will work with you to resolve each case. In your email, please provide us with the date of birth and country of origin of the matched recipient. Segovia will verify whether the recipient that failed screening is a "false positive," in which case we’ll place that person’s account number on our whitelist, so that future payments to that name-and-account combination won’t trigger a false match.

313 Missing Sender Information

The transaction didn't include enough information about the sender.

319 Transmission Failed Permanently

The gateway failed to send the transaction to the provider, and will not retry.

320 Operation Not Supported By Provider

The requested operation is not supported by the payment provider.

321 Currency Not Supported By Provider

The request specified a currency that isn’t supported by the payment provider.

330 Insufficient Funds

The payer account didn’t have enough funds to cover the requested payment.

3301 Wallet Is Below Minimum Balance

The wallet's available balance is below the minimum balance, and thus no new payments or subwallet funding operations may be performed.

3302 Would Exceed Wallet Negative Balance Limit

The requested transaction(s) would cause the wallet's balance to fall below its negative balance limit.

331 Payer Accounts Not Permitted

The transaction details included a payer account ID for a payment provider that doesn't support selecting specific payer accounts.

332 No Payer Account Specified

The transaction details didn't include a payer account ID for a payment provider that requires selecting specific payer accounts.

340 Transaction Too Small

The transaction amount was smaller than the minimum allowed size for this provider.

341 Transaction Too Large

The transaction amount was larger than the maximum allowed size for this provider.

342 Would Exceed Recipient Maximum Balance

The requested payment would cause the recipient's account to exceed its maximum balance. You may wish to ask the recipient to withdraw money from their account before you retry the payment. Note that this limit is imposed by the provider. In some cases, recipients can increase their maximum balance by making a request to their payment provider.

350 Timed Out, Cancelled

The provider failed to process the transaction in the amount of time allowed (this can vary by provider) and the transaction has been discarded. When this status code is returned, the gateway will have cancelled the transaction with the provider and no further action is required.

359 Timed Out, Not Cancelled

The provider failed to process the transaction in the amount of time allowed (this can vary by provider) and the transaction has been discarded. This status code indicates that the gateway was unable to confirm that the provider cancelled the transaction; manual intervention may be required.

361 Duplicate Payment Rejected by Provider

The provider rejected the transaction as a duplicate payment. Retrying the payment at a later time or with a slightly different amount may allow the payment to be processed.

370 Recipient Account Locked

The provider rejected the transaction because the recipient's account is locked or frozen and therefore can't receive payments.

371 Recipient Account Not Activated

The provider rejected the transaction because the recipient's account is not activated, or otherwise not configured to receive payments. For mobile money providers, this generally means that the recipient has a valid account with the provider but has not activated its mobile money functionality.

380 Invoice Not Acknowledged

The subscriber did not acknowledge the invoice transaction with a positive SMS reply.

381 Invoice Rejected By Subscriber

The subscriber indicated that they did not wish to complete the invoice transaction.

382 Invoice Expired

The subscriber indicated that they would complete the invoice transaction, but did not do so in time.

399 Rejected by Provider

The provider has refused to complete the transaction for a reason not covered by a more specific status code. The description included alongside the status code may include additional details.

400 Bad Request

The gateway couldn’t decode the transaction.

401 Unknown Client ID

The supplied client ID was invalid.

402 Unauthorized

The client attempted to initiate a transaction for which it didn’t have permission.

404 Transaction Not Found

The client requested the status of a transaction that isn’t known to the gateway. This is not a real status code that an actual transaction can have; it's only ever returned by /api/transactionstatus to indicate that the transaction being queried doesn't exist.

4041 Target Transaction Not Found

This transaction attempted to refer to another transaction, and the other transaction didn't exist. This is distinct from status code 404 in that the transaction with this status exists, but failed because another transaction also needed to exist. For example, a reversal transaction might have this status if it is an attempt to reverse a nonexistent transaction.

405 Payment Provider Not Found

The client specified a payment provider that isn’t known to the gateway.

406 Provider Autodetection Failed

The client specified that payment provider should be automatically inferred by the gateway from looking at the recipient account ID (which should be a phone number with country code), but the gateway cannot find a provider for the recipient.

407 Provider Not Available

The requested payment provider is temporarily unavailable. This can be due to a number of situations, for example, the provider may be undergoing scheduled maintenance.

410 Missing Fields

Required fields were missing.

420 Recipient Not Found

The provider doesn’t recognize the requested recipient (typically because the account number is wrong).

421 Payer Not Found

The provider doesn’t recognize the requested payer (typically because the account number is wrong).

430 Operation Not Valid

This transaction's operation wasn't valid.

4301 Target Transaction Not Successful

This transaction attempted to perform an operation that requires a successful transaction as its target, and the specified target transaction wasn't successful. For example, an attempt to reverse a failed payment would result in this status.

4302 Transaction Type Not Reversible

This transaction attempted to reverse a transaction of a type that is incapable of being reversed, such as a validate transaction.

4303 Transaction Already Reversed

The transaction whose reversal is being requested by this transaction has already been successfully reversed.

4304 Reversal Already Requested

There is already a pending reversal request for the transaction whose reversal this transaction is requesting.

4305 Too Late to Reverse Transaction

The transaction is no longer able to be reversed. For example, if the recipient has already spent the money from a payment, a provider might refuse to reverse the payment.

440 Wallet Not Found

The requested operation specified a wallet or subwallet that doesn't exist.

441 Subwallet Not Valid For Provider

The requested subwallet is not associated with a main wallet that's allowed to be used with the requested payment provider.

450 Subwallet Already Exists

A subwallet with the requested ID couldn't be created because it already exists.

460 Subwallet Is Deactivated

The requested subwallet couldn't be used because it is deactivated. Reactivate it, use a different subwallet, or use the main wallet.

470 Transfers Between Requested Wallets Not Permitted

The requested wallets and/or subwallets can't transfer funds to one another. Typically this status code would result from trying to transfer between two different main wallets; transfers are only allowed between a main wallet and its subwallets or between subwallets of the same main wallet.

500 Internal Error

Catch-all error code. An internal error occurred in the gateway that prevented the transaction from being successfully completed. The gateway will not automatically retry the transaction.