Introduction

Segovia’s objective is to make payments in emerging markets faster, more transparent, more reliable, and more secure. Segovia takes the pain out of managing payment in order to allow companies to focus on running their core business. We provide a single point of contact from a technical and customer service standpoint and aim to deliver a world class product on both fronts.

Segovia’s payment gateway offers a unified API to execute bulk payments through multiple payment providers (primarily mobile money) in a wide range of countries in emerging markets.

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 may be sent asynchronously using HTTPS requests from the payment gateway to the client or via polling from the client to the gateway. 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.

Getting Started

Integrating with Segovia's payment gateway is a straightforward process.

Decide on a client configuration for your development environment(s). Your Segovia technical contact will help you with this.
Install the test client and its dependencies. You'll get the test client from your Segovia technical contact.
Try sending requests to the payment gateway using the test client to verify that your configuration is correct.
Implement the integration in your code, using the API reference as a guide.
Test the integration using the test payment provider to verify your implementation.
Test the integration using real payment providers to confirm that payments are transmitted as expected.
Decide on a client configuration for your production environment.
Deploy your integration to production.
Test the integration using the test payment provider to confirm the production configuration.

The rest of this guide contains more detail about various elements of the process.

Client Configuration

Each payment gateway client has a number of configuration settings. These will be set by a Segovia administrator during the account creation process. It's worth noting that from the payment gateway's point of view, a "client" is an identity, not a specific piece of software.

Client ID

A textual unique identifier for this client, analogous to a username. The client ID will typically be assigned by Segovia; typically you'll get one client ID for developer use (multiple developers can use the same ID) and another for production use.

Callback URL

If configured, the payment gateway will always send callback requests to this client and will send them to the configured URL. In that case, it's impossible to specify an alternate callback URL in API requests. Configuring the client with a callback URL is recommended for production environments since it prevents transactions from being processed without the client being informed.

For environments that can't accept callbacks (e.g., development systems) this setting will not be present, and the caller will have to poll for the status of transactions.

Secret Key(s)

Each API request and response includes a signature that's generated using a secret key, which both the payment gateway and the client may use to confirm that a request is legitimate.

By default, the same key will be used for both incoming requests to the gateway and callback requests to the client. However, if desired, separate keys may be specified for incoming and outgoing requests.

Secret keys are required for all clients, whether production or development/test.

Installing the Test Client

The test client is a simple Python script that implements the payment gateway API. You'll get it from your Segovia representative as part of the account setup process. To use it, you'll need the following:

Python 3.4 or higher
The requests module (may be installed using pip)
The ssl module (should be installed by default on Python 3 if the system has OpenSSL)

Once the prerequisites are installed, simply copy the test client to your host and make it executable (e.g., by running chmod a+x client.py).

Using the Test Client

Command-Line Interface

The test client uses command-line options to control its configuration. Many of the options have corresponding environment variables whose values are used as defaults if the options aren't specified. It takes JSON as input and can produce either JSON or human-readable progress reports as output.

A summary of the command-line interface is printed if the client is run with no options; use the --help option for more detailed descriptions.

Two arguments are required: The hostname of the payment gateway instance to connect to (ordinarily this will be payment-api.thesegovia.com) and the API command to send. The command is the last part of the URL path for API requests, e.g., pay to send an /api/pay request.

Option	Default	Description
`-c ID` `--client ID`	`$PAYMENT_CLIENT_ID`	The ID of the client making the request, as assigned during the client configuration process. Required.
`-C FILE` `--certfile FILE`	`$PAYMENT_SSL_CERT`	If callbacks are enabled, the SSL certificate to use when accepting connections from the payment gateway. Ignored if callbacks aren't enabled. Required if the `-l` option is specified.
`-g` `--generate-ids`		Generate random IDs for any transactions that don't already have IDs in the input JSON. Otherwise the input is required to include transaction IDs.
`-H HOST` `--hostname HOST`	`$PAYMENT_CALLBACK_HOST`	Which hostname to tell the payment gateway to use for callback requests. The callback hostname must be specified if the `-l` option is used.
`-l` `--listen`		Listen for callback requests rather than polling for results. Only use this option if your system is reachable from the public Internet.
`-p PORT` `--port PORT`	8765	If callbacks are enabled, the port number to listen on for callback requests.
`-r KEY` `--request-key KEY`	`$PAYMENT_REQUEST_KEY`	Secret key to use for outgoing requests to the gateway. May be the same as the response key. Required.
`-R KEY` `--response-key KEY`	`$PAYMENT_RESPONSE_KEY`	Secret key to use for callback requests from the gateway. May be the same as the request key. Required.
`--run COMMAND`		Run the specified command to get the input to the API request rather than reading from standard input.
`-v` `--verbose`		Show debugging output including JSON responses rather than human-readable progress summaries.

JSON Format

The JSON object format for each API request is described in the API reference documentation.

Default Values

Generally speaking, the test client accepts JSON in the same format as the payment gateway API. However, the client can fill in default values for several API fields if they're missing from the input:

For all requests
callbackArgs (always populated by the test client even if specified in input JSON)
callbackUrl (populated if the -l option is used)
clientId (populated with the client ID from the -c option or the PAYMENT_CLIENT_ID environment variable)
requestId
For each element of the transactions list in requests that create new transactions (e.g., /api/pay, /api/lookup, /api/validate)
transactionId

Example Input

A batch of three payments to two payment providers:

{
  "requestId": "769b870d-5031-4121-98f1-b86b4985037b",
  "batchReference": "test-batch-12345",
  "transactions": [
    {   
      "transactionId": "d7722446-b568-4d52-9d4a-c9943b8f17f2",
      "provider": "mtn-rwanda",
      "currency": "RWF",
      "recipientAccountId": "250123456789",
      "name": "Mathias Ntawulikura",
      "amount": 235
    },{
      "transactionId": "2737d553-9c76-4207-80a5-fe5e1cec56a1",
      "provider": "safaricom-kenya",
      "currency": "KES",
      "recipientAccountId": "254123456789",
      "amount": 15,
      "name": "Jemima Sumgong"
    },{
      "transactionId": "8d92ee08-2ca3-45f7-b69e5e3c224de246",
      "provider": "paga-nigeria",
      "currency": "NGN",
      "recipientAccountId": "234123456789",
      "amount": 30,
      "name": "Olanna Ozobia"
    }   
  ]
}

The Test Payment Provider

In addition to the real payment providers, the gateway has a payment provider called test that may be used for testing and for monitoring the health of the payment gateway. No money is ever transmitted by the test provider.

By default, the test provider will allow all transactions to succeed. However, to support testing response handling in client code, it supports a set of directives which force it to reject transactions in various ways. The directives should be placed in the otherParams field of the transaction data. Unless otherwise mentioned, directives can be combined by including multiple entries in the otherParams list, one directive per entry.

Key	Value Type	Description
`statusCode`	Integer	Force the transaction to result in the specified status code. Only final status codes are allowed, not informational ones (that is, the value must be a code of types `succeeded` or `failed`).
`latency`	Integer	Simulate payment provider latency by waiting this many milliseconds before simulating sending the transaction to a provider. This may be used to test handling of informational status updates. By default, the gateway will simulate a latency of between 250 and 750 milliseconds (randomly selected).
`resultDelay`	Integer	Delay the transaction for this many milliseconds (in addition to the `latency` delay) before returning the result to simulate provider processing time. By default, the gateway will simulate a processing time of between 1000 and 2000 milliseconds (randomly selected).
`statuses`	Array	A list of delays and status codes to send, to support reproducible testing of different error-handling scenarios. Each array element is an object whose fields are described below. If this array is present, the `statusCode`, `latency`, and `resultDelay` fields are ignored.

If the statuses array is specified, each array element should be a JSON object with the following fields.

Key	Value Type	Description
`delay`	Decimal	Number of seconds to wait before updating the status of the transaction. Must be greater than or equal to 1, and less than 120 (i.e. two minutes). Note that this is a minimum value, and the actual delay may be higher; in particular, for clients using callback requests, the gateway has a pre-callback delay to allow multiple status updates to be batched together in one callback.
`statusCode`	Integer	Status code to send. The last element in the `statuses` array, and only the last element, must contain a final status code; all other elements must contain informational status codes.
`description`	String	Optional. If specified, this description will be used instead of the default one.

Note that it's entirely possible to construct a statuses array with a list of status updates that would never occur in actual use; care should be taken to design reasonable test cases.

Simulating Collections

To test your client's handling of collections, send an /api/collect/test API request to the gateway. This will cause the gateway to generate a fake payment to you, and, if configured, will send callback requests to your application. See the API reference for more details.

Payment Provider Autodetection

In some cases, it is possible for the payment gateway to automatically determine which payment provider should be used for a given recipient account ID. For example, in some countries, mobile carriers are assigned phone number prefixes such that a given phone number can only ever belong to a customer of a particular carrier, in which case only that carrier's mobile money service can pay the recipient.

Autodetection is enabled by setting the payment provider name to the string autodetect in the request JSON. If possible, the gateway will determine which provider to use.

Autodetection is not always possible for a variety of reasons. The most common one is that a country's mobile carriers support phone number portability, such that a customer of carrier A can switch to carrier B and keep the same phone number. In that case there is no way for the payment gateway to determine which carrier to use. If the payment gateway is unable to autodetect the provider for a transaction's recipient account ID, the transaction will fail with status code 406 (provider autodetection failed).

SMS

The gateway can also send SMS messages upon request. This feature allows customers to use SMS for a number of payment-related use cases. A typical use case is to make payments from Segovia with providers that don't support the "reason" field clearer for the recipient - a followup SMS could clarify the origin and intent of the transaction that has just happened.

By default, SMS messages sent by the gateway will still originate from Segovia's mobile account. An optional sender account ID can be passed to the gateway, and the gateway will use it instead, if possible.

The gateway currently only supports sending SMS messages; in the future, the gateway might also support receiving SMS messages.

The gateway also only supports SMS sending in a subset of countries that payments are supported.