bk-api-sdk 1.0.0

The Boku Direct Payments API is a payment gateway API that enables merchants to accept payments through local payment methods such as digital wallets and carrier/mobile billing. It acts as a bridge between merchants and payment issuers (wallets, mobile carriers, etc.).

Getting Started with Boku Direct Payments API

Introduction

API Security

Security is a significant consideration for payment platforms. As part of the registration process for each registered merchant account, merchants receive a security key used to authenticate communications in either direction.

Developers should consult the Boku API Signature Authentication Guide for additional details with respect to implementing security on the Boku APIs.

API Usage

When a consumer chooses to use a local payment-method (wallet), the consumer must go through an 'optin' flow to authenticate. This is accomplished using a redirect to the issuer's app or website where the consumer authenticates and completes the opt-in process.

After the consumer adds their local payment-method (wallet), as their registered payment method, the 'charge' method is used to charge the consumer's local payment-method.

If a customer decides to refund a transaction, the 'refund-charge' method can be used to refund the transaction.

API Versioning

The Boku Payment Gateway API is versioned to provide support for changes to functionality without affecting existing integrations. Each API URL includes version information that enables distinct functionality across different versions.

There are several types of changes that could result in a new API version:

1. New API functionality – new APIs, new parameters, additional information in responses, improved error reporting.
2. Deprecated API functionality – deprecated APIs, deprecated parameters, deprecated error messages.
3. Changes in functionality – existing functional behavior changes such as the returned result of a call. A warning is changed to an error. Validation becomes stricter or more lenient.

In these cases, Boku will release a new API version through a new endpoint(s). When new versions of existing APIs are added, support for existing versions is maintained. Unless otherwise stated, as a rule, compatibility is maintained across versions. Prior supported endpoints should have unchanged behavior. If an API is deprecated and scheduled to be removed, a notice of not less than 6 months will be given. Requests for extensions to this period can be considered.

Boku may make changes to the API within an existing version without changing the version number. An example of a non-versioning change would be the addition of an optional field to a request or to a response.

API Calls

URL Scheme

All the below API calls are against URLs that follow the pattern,

https://${api-node}.boku.com/${api-family}/${api-version}/${api-call}

Definitions for the above placeholders:

• api-node: This follows the pattern '${country}-api4' (e.g. 'us-api4').
  • 'country' is the two letter country code of the end-user's payment-method against which the call is made.
  • The country code is required and is used for more efficient routing of the request.
  • The country code in the url must match the country code supplied in the optin-request.country element.
• api-family: Groups a family of related API methods.
  • In this API, family is either one of:
    • 'optin' - For interacting with the user or handset to obtain billing approval.
    • 'billing' - For actually performing billing operations against the user.
• api-version: In this version of the API, this value is always the string '3.0'.
  • Calls under different version numbers may be used in the future to introduce non-compatible API changes.
• api-call: The name particular API call or method to invoke, for example 'charge' or 'refund-charge'.
  • This usually matches the XML root element name, sans the '-request' suffix.

Fully qualified API call URLs are documented with each of the example calls detailed below.

Install the Package

The package is compatible with Python versions 3.7+. Install the package from PyPi using the following pip command:

pip install bk-api-sdk==1.0.0

You can also view the package at: https://pypi.python.org/pypi/bk-api-sdk/1.0.0

Test the SDK

You can test the generated SDK and the server with test cases. unittest is used as the testing framework and pytest is used as the test runner. You can run the tests as follows:

Navigate to the root directory of the SDK and run the following commands

pip install -r test-requirements.txt pytest

Initialize the API Client

Note: Documentation for the client can be found here.

The following parameters are configurable for the API Client:

Parameter	Type	Description
country	str	Country code in ISO 3166-1-alpha-2 standard Default: "gb"
environment	Environment	The API environment. Default: Environment.MERCHANT_TEST_ENVIRONMENT
http_client_instance	Union[Session, HttpClientProvider]	The Http Client passed from the sdk user for making requests
override_http_client_configuration	bool	The value which determines to override properties of the passed Http Client from the sdk user
http_call_back	HttpCallBack	The callback value that is invoked before and after an HTTP call is made to an endpoint
timeout	float	The value to use for connection timeout. Default: 60
max_retries	int	The number of times to retry an endpoint call if it fails. Default: 0
backoff_factor	float	A backoff factor to apply between attempts after the second try. Default: 2
retry_statuses	Array of int	The http statuses on which retry is to be done. Default: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524]
retry_methods	Array of string	The http methods on which retry is to be done. Default: ["GET", "PUT"]
proxy_settings	ProxySettings	Optional proxy configuration to route HTTP requests through a proxy server.

The API client can be initialized as follows:

Code-Based Client Initialization

from bokudirectpaymentsapi.bokudirectpaymentsapi_client import BokudirectpaymentsapiClient
from bokudirectpaymentsapi.configuration import Environment

client = BokudirectpaymentsapiClient(
    environment=Environment.MERCHANT_TEST_ENVIRONMENT,
    country='gb'
)

Environment-Based Client Initialization

from bokudirectpaymentsapi.bokudirectpaymentsapi_client import BokudirectpaymentsapiClient

# Specify the path to your .env file if it’s located outside the project’s root directory.
client = BokudirectpaymentsapiClient.from_environment(dotenv_path='/path/to/.env')

See the Environment-Based Client Initialization section for details.

Environments

The SDK can be configured to use a different environment for making API calls. Available environments are:

Fields

Name	Description
MERCHANT_TEST_ENVIRONMENT	Default
PRODUCTION_ENVIRONMENT	-

List of APIs

• Consumer Registration
• Account Resources
• Config Resources
• Charge
• Refund
• Forex
• Fund-Check
• Seller of Record

SDK Infrastructure

Configuration

• ProxySettings
• Environment-Based Client Initialization

HTTP

• HttpResponse
• HttpRequest

Utilities

• ApiHelper
• HttpDateTime
• RFC3339DateTime
• UnixDateTime