Introduction

TakeMe Pay (TMP) helps you accept payments from various sources - from offline QR code payment, to app/web based e-commerce, recurring billing and even POS integration. Follow this document to start building your payment flow.

To get started, you only need three steps:

Obtain your API keys. Contact us to get your TMP account and API keys, which are required for both TMP HTTP API and native SDK.
Install and integrate an API library with your app. Download and install native iOS/Android SDK, or use our HTTP API directly, so you can integrate TMP into your app in minutes.
Prepare HTTP API to talk with our server. you'll need the following API on your server: user validation (get an ephemeral key for each session), charge creation (the actual payment), and Webhooks (receive events like payment results from us).

Tutorials

Overview

Integrating with TakeMe Pay SDK takes the following steps:

Get API keys.
Add TakeMe Pay SDK to your project.
Use TakeMe Pay SDK in your app to make payments.
Prepare your server-side API to receive notifications and send acknowledgements from/to our server.

Integration - iOS

TakeMe Pay is a payment aggregator that gives you access to dozens of payment brands via an unified API. This article explains how to integrate TakeMe Pay SDK into your iOS apps.

We'll walk you through the integration process using a demo iOS app called Coffee Delivery. The app allows you to order a cup of coffee and pay for it, as shown in the picture below:

CoffeeDelivery

Getting Started

Please make sure that you have access to a mainland Chinese user account. As of now, the WeChat platform may not allow non-Chinese citizens to use WeChat abroad. If you encounter errors, please check to make sure that you are using a mainland Chinese user account first.

To make it easier for you, we have provided our tutorial project in both Objective-C and Swift with the core features of Coffee Delivery, but without the integration of the SDK. Go ahead and download the project, then open it in Xcode.

If you want to see the finalized Xcode project, it's also available.

REMINDER: Remember to add "AppTransportSecurity" if you have not already. You can find more information about that here

NOTE:

If you are using SWIFT, then you need to have a bridging header if you do not already have one. You can find more information on bridging headers here

Then add the following to your bridging header file:

#import <TakeMePaySDK/TakeMePaySDK.h>

Get API Keys

You'll need public key and secret key for SDK and server-side integrations, respectively. If you don't have them already, please contact our sales team.

You'll also need WeChat Pay App ID if you want WeChat Pay. To obtain this app id, you can either become a WeChat developer on the WeChat Open Platform and get the app id from them, or ask us to issue a app id on behalf of you.

Install TakeMe Pay SDK into Your App

Installation is quite simple using CocoaPods:

Add these to your Podfile:

pod 'TakeMePaySDK'

pod 'TakeMePaySDK-WeChatPaySupport'

Navigate to the project's directory in Terminal.
Run pod install.

Depending on your CocoaPods configuration and version, you may need to change its platform to 10.0 in your Podfile, e.g. platform :ios, '10.0'.

You can, also, choose to install the SDK the manual way. Just download TakeMePaySDK and TakeMePaySDK-iOS-WeChatPaySupport frameworks and manually put them into your Xcode project folder.

Use TakeMe Pay SDK in your app

First of all, we strongly recommend you add environment variable TMP_PRINT_CONSOLE_LOG to your Xcode scheme so that you can see logs output by the SDK, directly in Xcode. To do this, open the Coffee Delivery project in Xcode, edit the target scheme, click Arguments section, click + button to add a new environment variable, use TMP_PRINT_CONSOLE_LOG as the key and 1 as the value.

Now, let's update a few files to actually add the SDK.

Step 1

We need to add the API keys.

OBJECTIVE-C

Open AppDelegate.m, find application:didFinishLaunchingWithOptions:launchOptions: (should be the first method), and add the following lines:

TakeMePay.publicKey = @"your public key"; // public key got from TakeMePay's platform previously and will be used to authenticate all network requests with TakeMe Pay server

TakeMePay.wechatPayAppId = @"your WeChat Pay App ID"; // fill the WeChat Pay app id which you got from WeChat Open Platform

SWIFT

Open AppDelegate.swift, find application(didFinishLaunchingWithOptions:) (should be the first method), and add the following lines: ```swift TakeMePay.publicKey = "pk_test_sDkS-Zn8sf8iv0HgW7S9HBLd1LRwk7aAQ9yWVghD"

TakeMePay.wechatPayAppId = "wxf2ac9aae739daee5" ```

Step 2

We should edit the URL Type by navigating to the project Target "Coffee Delivery" Go to Info, then click the '+' button to add a URL Type. Under the 'URL Schemes', you need to put your Wechat Pay scheme (same as your TakeMePay.wechatPayAppID) as the "Editor" Role.

Also, because the payment needs to jump to Wechat app, we need to add the scheme of Wechat in the Info.plist, under the LSApplicationQueriesSchemes key, to support the redirection, for more information, you could check the reference here

Step 3

We need to handle the url jumping back request, add application:openURL:options::

OBJECTIVE-C

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    return [TakeMePay shouldHandleUrl:url];
}

SWIFT

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    return TakeMePay.shouldHandle(with: url)
}

This method handles all url opening requests, so if you need to handle more than just our url, you should handle others by yourself, continue passing the current url to other logic after [TakeMePay shouldHandleUrl:url] returns NO, which means the url is not the responsibility of TakeMePay SDK.

Step 4

We need to show the checkout UI and accept the payment.

OBJECTIVE-C

Open TMPCoffeeBuyingViewController.m and add these code to the pay: method:


// 1. According to your needs, you could use this convenience initializer to generate a TMPSourceParams object
TMPSourceParams *params = [[TMPSourceParams alloc] initWithDescription:@"Coffee Delivery Service" amount:10 currency:@"JPY"];

// 2. Generates a TMPPayment object, which is the core part of once payment progress

// If you don't have requirement to implement your own SourceParamsPreparer, you can just use our built-in SourceParamsPreparer for convenience, the delegate is the recipient of payment message callbacks
TMPPayment *payment = [[TMPPayment alloc] initWithSourceParams:params delegate:self];

// sourceParamsPreparer is responsible for "modifying and decorate" the primitive params (such as selecting a specific payment channel through the UI, or filling in some other necessary information, and finally returning the params to the payment object that meets the required requirements, in this case, we use the SDK build-in preparer to enable the default UI. Of course, developer can fully customize a preparer, even create a payment without any UI intervention, depending on the developer's needs

// TMPPayment *payment = [[TMPPayment alloc] initWithSourceParams:params sourceParamsPreparer:[[YourCustomSourceParamsPreparer alloc] init] delegate:self];

// 4. start the payment process
[payment startPaymentAction];

// Or, we provide another `startPaymentAction:` method to take a dictionary for extra information, if you use our built-in SourceParamsPreparer, and the device supports Apple's Tapic Engine technology, you can pass an extra information dictionary like:
// [payment startPaymentAction:@{@"useTapicEngine" : @(YES)}];

SWIFT

Open ViewController.swift and add the following code to the payButtonAction: method:

        // 1. init a source params with necessary information.
        // 2. create TMPPayment from sourceParams, ephemerKeyProvider and delegate.
        guard !isInProgress,
            let params = TMPSourceParams(description: "Coffee Delivery Service", amount: 10, currency: "JPY"),
            let payment = TMPPayment(sourceParams: params, delegate: self) else {
            return
        }

        self.isInProgress = true

        // 3. start payment action. ( with optional tapic engine impact )
        payment.startAction(["useTapticEngine": true])

For receiving payment result, you could implement payment(didFinishWithState:) method to get the result of the payment, In this demo, we are going to pop up an alert view with specific payment result state.

You can compare your code against the full source code for your reference.

If you run the project now, you should be able to see the checkout UI.

But hold on! You are one step away from making a payment successfully. See Prepare your server-side API for details

Test

Once you have the demo server implementation up and running, finally it's time to run Coffee Delivery in Xcode on your iOS device.

Integration - Android

Integration

Add TakeMe Pay's Maven repository:

repositories {
    maven { url 'https://maven.takemepay.com' }
}

Then add following dependency into your app project:

dependencies {
    implementation 'com.takemepay:sdk:1.0'
}

Setup

Use TakeMePay.init() to setup with a Configuration. You'll have to initialize TakeMe Pay SDK before using it, otherwise there'll be an error. Usually this is done in Application.onCreate()

import com.takemepay.sdk.Configuration;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        TakeMePay.init(this, Configuration.newBuilder()
            .publishableKey("YOUR KEY HERE")
            .weChatAppId("YOUR APPID HERE")
            .distributedUrlSchemeHost("YOUR SCHEME HERE")
            .build());
    }
}

Start a payment

To start a payment process, use TakeMePayUi.Builder to create an Intent, and call startActivityForResult() with that intent.

Get response

You can determine if the payment successful by checking returnCode in onActivityResult.

TakeMePay.RESPONSE_OK means payment successful, also a Source will be included in return result.

Other response will be returned, in case of problem happens.

Theme Customization

To make TakeMe Pay payment UI adapt your own branding style, you can customize its Look & Feel by following steps:

1. Create a style in your resources

<style name="Theme.MyApp.Payment" parent="TakeMePay.PaymentDialog">
        <item name="android:windowBackground">@android:color/transparent</item>

        <item name="confirmPayButtonColor">#0179FF</item>
        <item name="confirmPayButtonCornerRadius">4dp</item>
        <item name="confirmPayButtonTextColor">#FFFFFF</item>
        <item name="contentDividerColor">#eeeeee</item>
        <item name="actionSheetBackgroundColor">#FFFFFF</item>
        <item name="commodityNameTextColor">#253955</item>
        <item name="commodityNameTextSize">16sp</item>
        <item name="commodityPriceTextColor">#3c444f</item>
        <item name="commodityPriceTextSize">36sp</item>
        <item name="paymentMethodTextColor">#131111</item>
        <item name="paymentMethodTextSize">16sp</item>
</style>

2. Specify your theme before launching Payment UI

final Intent intent = new TakeMePayUi.Builder(v.getContext())
        .sourceParams(params)
        .useDelegate(true)
        .overrideTheme(R.style.Theme_MyApp_Payment) // <=== Add this call
        .build();
startActivityForResult(intent, REQUEST_CODE);

Completely take control of the UI

If you want to use your own payment UI instead of TakeMe Pay provided, you may want to use PaymentController. Use retrieveSourceTypeList to get list of supported payment method, and startPaymentRequest to get Intent of payment process for startActivityForResult with selected method. You can call handlePaymentActivityResult in onActivityResult to retrieve payment result.

Evaluation Usage

To give TakeMePay a try, without applying TakeMePay API key or WeChat merchant account, you can use TakeMePay Payment Delegate to try payment process. Configure via useDelegate in TakeMePayUi.Builder will make debug builds use delegate.

Prepare your server-side API

To make a payment in demo application, you'll need some server-side API to talk to the TakeMe Pay server. This is because when you try to make a payment in the iOS app, TakeMe Pay server will talk to your server to confirm the payment result via HTTPS requests. While the two sides are negotiating, TakeMe Pay SDK will wait, until the server-to-server conversation is over (or after certain amount of time, a.k.a timeout), and update its checkout UI to reflect the result.

The full technical details, as well as how you should implement your server API, is covered here. At this time, you can simply download our demo server implementation and run it on your own server, so you don't have to roll out your own one.

The demo server implementation is a single executable file, written in Go-lang, and can be run almost everywhere.

Questions?

We're more than happy to help with any questions you have! Feel free to talk to our sales team.

API Reference

# Base URL (Alpha Test)
https://api-stg.takemepay.com/v1

TakeMePay API is in REST style with intuitive resource base URLs and verbs. It uses standard HTTP authentication, response codes and standard JSON format for both request and response. Every API only works in HTTPS, plain HTTP is not supported for security reasons.

TakeMePay API can be used in test mode. The API key determines if one request is in test mode or live mode, which can be found in the response liveMode attribute. Data in test mode does not affect production live data and vice versa.

There 4 types of API key:

Secret test API key, with prefix sk_test_
Public test API key, with prefix pk_test_
Secret live API key, with prefix sk_live_
Public test API key, with prefix pk_live_

API authentication uses standard Bearer Authentication HTTP header: "Authorization: Bearer <token>".

Sources

Endpoint	Function
POST /sources	Create a source
GET /sources/:id	Retrieve a source
GET /sources	Retrieve sources

Source objects allow you to start a payment. They contain payment information related to specific payment method. Once validated and become chargeable, they can be charged.

## Source
{
    "id": "src_GvU0BtCVT_-NBJ8PlE1WZw",
    "object": "source",
    "amount": 150,
    "currency": "JPY",
    "type": "WeChatPay",
    "clientSecret": "src_cs_OPWZwU0BACXTA1NBJ8PlE1",
    "description": "takeme pay",
    "liveMode": false,
    "metadata": {},
    "status": "canceled",
    "created": 1544414761,
    "updated": 1544414761
}

The source object

Attribute	Type	Meaning
id	string	Unique identifier
object	string	Object's resource type
amount	integer	Payment amount in the smallest currency unit
currency	string	Currency code in ISO 4217. Available values: `JPY`
type	string	Type of the source. Available values: `WeChatPay`
clientSecret	string	Secret to enable client-side retrieval the same source using a public key
description	string	Description of the source. Can be displayed to the user for some payment method
liveMode	boolean	Flag indicates whether this object is in test mode or live mode
metadata	hashmap	Key-value pairs attached to the object. Can be useful to store additional data about the object
status	string	Status of the object. Available values: `pending`, `chargeable`, `consumed`, `failed`
created	integer	Created timestamp in Unix epoch milliseconds
updated	integer	Updated timestamp in Unix epoch milliseconds

Create a source

Request

## Create source
## POST /sources
curl -X "POST" "https://api-stg.takemepay.com/v1/sources" \
     -H 'Authorization: Bearer pk_test_your_public_or_secret_key' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
        "amount": 1,
        "currency": "JPY",
        "type": "WeChatPay"
    }'

Argument	Type	Required	Meaning
amount	integer	yes	Payment amount in the smallest currency unit
currency	string	yes	Currency code in ISO 4217. Available values: `JPY`
type	string	yes	Type of the source. Available values: `WeChatPay`
description	string	no	Description of the source. Can be displayed to the user for some payment method
metadata	hashmap	no	Key-value pairs attached to the object. Can be useful to store additional data about the object

Response

Returns a newly created source object.

## Create source response
{
    "id": "src_HtYWBZWZQM2OESJYJxAfkQ",
    "amount": 1,
    "currency": "JPY",
    "liveMode": false,
    "metadata": {},
    "payload": {},
    "status": "pending",
    "type": "WeChatPay",
    "clientSecret": "src_cs_Jj1uRu5uTFmwGteDXHME0g",
    "description": null,
    "created": 1556262090000,
    "updated": 1556262090000,
    "object": "source"
}

Retrieve a source

Request

## Retrieve source 
## GET /sources/:id
curl "https://api-stg.takemepay.com/v1/sources/src_HtYWBZWZQM2OESJYJxAfkQ" \
     -H 'Authorization: Bearer pk_test_your_api_key' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
        "clientSecret": "src_cs_Jj1uRu5uTFmwGteDXHME0g"
    }'

Argument	Type	Required	Meaning
id	string	yes	Unique identifier of the object
clientSecret	string	no	Secret to enable client-side retrieval the same source using a public key

Response

Returns an existent source object.

## Retrieve source response
{
    "id": "src_HtYWBZWZQM2OESJYJxAfkQ",
    "amount": 1,
    "currency": "JPY",
    "liveMode": false,
    "metadata": {},
    "payload": {},
    "status": "pending",
    "type": "WeChatPay",
    "clientSecret": "src_cs_Jj1uRu5uTFmwGteDXHME0g",
    "description": null,
    "created": 1556262090000,
    "updated": 1556262090000,
    "object": "source"
}

Retrieve sources

Request

## Retrieve sources
## GET /sources
curl "https://api-stg.takemepay.com/v1/sources" 
    -H "Authorization: Bearer sk_test_your_secret_api_key" \
    -H 'Content-Type: application/json; charset=utf-8'

Query string	Type	Required	Meaning
endingBefore	string	no	Pagination cursor to fetch the previous page
startingAfter	string	no	Pagination cursor to fetch the next page
limit	integer	no	Objects limit of one page

Response

Returns a list object with source data

## Retrieve sources response
{
  "hasMore": false,
  "data": [
    {
        "id": "src_HtYWBZWZQM2OESJYJxAfkQ",
        "amount": 1,
        "...": "..."
    }
  ],
  "object": "list"
}

Charges

Endpoint	Function
POST /charges	Create a charge
GET /charges/:id	Retrieve a charge
GET /charges	Retrieve charges

Charge objects allow to you charge a Source that is chargeable. Once the charge succeeds, the payment is completed.

## Charge
{
    "id": "ch_NBJ8PlE1WZGvU0BtCVT_-w",
    "object": "charge",
    "amount": 150,
    "currency": "JPY",
    "sourceId": "src_HtYWBZWZQM2OESJYJxAfkQ",
    "source": {},
    "description": "takeme pay charge",
    "liveMode": false,
    "metadata": {},
    "refunded": false,
    "status": "succeeded",
    "failureCode": null,
    "failureMessage": null,
    "created": 1556091482000,
    "updated": 1556091482000
}

The charge object

Attribute	Type	Meaning
id	string	Unique identifier
object	string	Object's resource type
amount	integer	Payment amount in the smallest currency unit
currency	string	Currency code in ISO 4217. Available values: `JPY`
sourceId	string	Source object id of the charge
source	object	Source object of the charge
description	string	Description of the charge. Can be displayed to user for some payment method
liveMode	boolean	Flag indicates whether this object is in test mode or live mode
metadata	hashmap	Key-value pairs attached to the object. Can be useful to store additional data about the object
refunded	boolean	Flag indicates whether the charge is refunded or not
status	string	Status of the object. Available values: `pending`, `succeeded`, `failed`
created	integer	Created timestamp in Unix epoch milliseconds
updated	integer	Updated timestamp in Unix epoch milliseconds

Create a charge

Request

## Create charge
## POST /charges
curl -X "POST" "https://api-stg.takemepay.com/v1/charges" \
     -H 'Authorization: Bearer sk_test_your_secret_api_key' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
        "amount": 150,
        "currency": "JPY",
        "sourceId": "src_HtYWBZWZQM2OESJYJxAfkQ"
    }'

Argument	Type	Required	Meaning
amount	integer	yes	Payment amount in the smallest currency unit
currency	string	yes	Currency code in ISO 4217. Available values: `JPY`
sourceId	string	yes	Source object id of the charge
description	string	no	Description of the source. Can be displayed to user for some payment method
metadata	hashmap	no	Key-value pairs attached to the object. Can be useful to store additional data about the object

Response

Returns a newly created charge object.

## Create charge response
{
    "id": "ch_NBJ8PlE1WZGvU0BtCVT_-w",
    "object": "charge",
    "amount": 150,
    "currency": "JPY",
    "sourceId": "src_HtYWBZWZQM2OESJYJxAfkQ",
    "source": {},
    "description": "takeme pay charge",
    "liveMode": false,
    "metadata": {},
    "refunded": false,
    "status": "succeeded",
    "failureCode": null,
    "failureMessage": null,
    "created": 1556091482000,
    "updated": 1556091482000
}

Retrieve a charge

Request

## Retrieve charge 
## GET /charges/:id
curl "https://api-stg.takemepay.com/v1/charges/ch_NBJ8PlE1WZGvU0BtCVT_-w" \
     -H 'Authorization: Bearer sk_test_your_secret_api_key'

Argument	Type	Required	Meaning
id	string	yes	Unique identifier of the object

Response

Returns an existent charge object.

## Retrieve charge response
{
    "id": "ch_NBJ8PlE1WZGvU0BtCVT_-w",
    "object": "charge",
    "amount": 150,
    "currency": "JPY",
    "sourceId": "src_HtYWBZWZQM2OESJYJxAfkQ",
    "source": {},
    "description": "takeme pay charge",
    "liveMode": false,
    "metadata": {},
    "refunded": false,
    "status": "succeeded",
    "failureCode": null,
    "failureMessage": null,
    "created": 1556091482000,
    "updated": 1556091482000
}

Retrieve sources

Request

## Retrieve charges
## GET /charges
curl "https://api-stg.takemepay.com/v1/charges" 
    -H "Authorization: Bearer sk_test_your_secret_api_key" \
    -H 'Content-Type: application/json; charset=utf-8'

Query string	Type	Required	Meaning
endingBefore	string	no	Pagination cursor to fetch the previous page
startingAfter	string	no	Pagination cursor to fetch the next page
limit	integer	no	Objects limit of one page

Response

Returns a list object with charge data

## Retrieve charges response
{
  "hasMore": false,
  "data": [
    {
        "id": "ch_NBJ8PlE1WZGvU0BtCVT_-w",
        "amount": 150,
        "...": "..."
    }
  ],
  "object": "list"
}

Refunds

Endpoint	Function
POST /refunds	Create a refund
GET /refunds/:id	Retrieve a refund

Refunds objects allow you to refund a charge. Once a charge is succeeded, you can use it's id to refund.

## Refund
{
    "id": "refund_W2v3SfpZSCuc08dO-fAarQ",
    "object": "refund",
    "amount": 150,
    "currency": "JPY",
    "reason": null,
    "chargeId": "ch_NBJ8PlE1WZGvU0BtCVT_-w",
    "liveMode": false,
    "metadata": {},
    "status": "pending",
    "failureReason": null,
    "created": 1544414761,
    "updated": 1544414761
}

The refund object

Attribute	Type	Meaning
id	string	Unique identifier
object	string	Object's resource type
amount	integer	Payment amount in the smallest currency unit
currency	string	Currency code in ISO 4217. Available values: `JPY`
reason	string	Reason of the refund. Can be displayed to the user for some payment method
chargeId	string	Charge object id of the refund
liveMode	boolean	Flag indicates whether this object is in test mode or live mode
metadata	hashmap	Key-value pairs attached to the object. Can be useful to store additional data about the object
status	string	Status of the object. Available values: `pending`, `succeeded`, `failed`
failureReason	string	Failure reason if the refund failed
created	integer	Created timestamp in Unix epoch milliseconds
updated	integer	Updated timestamp in Unix epoch milliseconds

Create a refund

Request

## Create refund
## POST /refunds
curl -X "POST" "https://api-stg.takemepay.com/v1/refunds" \
     -H 'Authorization: Bearer sk_test_your_secret_api_key' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
        "chargeId": "ch_NBJ8PlE1WZGvU0BtCVT_-w"
    }'

Argument	Type	Required	Meaning
chargeId	string	yes	Unique identifier of the charge to refund
reason	string	no	Reason of the refund. Can be displayed to the user for some payment method
metadata	hashmap	no	Key-value pairs attached to the object. Can be useful to store additional data about the object

Response

Returns a newly created refund object.

## Create refund response
{
    "id": "refund_W2v3SfpZSCuc08dO-fAarQ",
    "object": "refund",
    "amount": 150,
    "currency": "JPY",
    "reason": null,
    "chargeId": "ch_NBJ8PlE1WZGvU0BtCVT_-w",
    "liveMode": false,
    "metadata": {},
    "status": "pending",
    "failureReason": null,
    "created": 1544414761,
    "updated": 1544414761
}

Retrieve a refund

Request

## Retrieve refund 
## GET /refunds/:id
curl "https://api-stg.takemepay.com/v1/refunds/refund_W2v3SfpZSCuc08dO-fAarQ" \
     -H 'Authorization: Bearer sk_test_your_secret_api_key' \
     -H 'Content-Type: application/json; charset=utf-8'

Argument	Type	Required	Meaning
id	string	yes	Unique identifier of the object

Response

Returns an existent refund object.

## Retrieve refund response
{
    "id": "refund_W2v3SfpZSCuc08dO-fAarQ",
    "object": "refund",
    "amount": 150,
    "currency": "JPY",
    "reason": null,
    "chargeId": "ch_NBJ8PlE1WZGvU0BtCVT_-w",
    "liveMode": false,
    "metadata": {},
    "status": "succeeded",
    "failureReason": null,
    "created": 1544414761,
    "updated": 1544414761
}

Events

Endpoint	Function
GET /events	List all events
GET /events/:id	Retrieve an event

Events objects hold information about something happened in your TakeMePay account. You can create Webhooks to get notified when Events happen.

## Events
{
    "id": "evt_HxVoR5mYSc-2Ob2rvT2ApQ",
    "liveMode": false,
    "object": "event",
    "type": "source.created",
    "created": 1556265228475,
    "data": {
      "dataObject": {},
      "previousObject": {}
    }
}

The event object

Attribute	Type	Meaning
id	string	Unique identifier
object	string	Object's resource type
liveMode	boolean	Flag indicates whether this object is in test mode or live mode
type	string	Type of the event
created	integer	Created timestamp in Unix epoch milliseconds
data	object	Data objects of the event
data.dataObject	object	Current data of resource relevant to the event
data.previousObject	object	Previous data of resource relevant to the event

Retrieve events

Request

## Retrieve events
## GET /events
curl "https://api-stg.takemepay.com/v1/events" \
    -H "Authorization: Bearer sk_test_your_secret_api_key" \
    -H 'Content-Type: application/json; charset=utf-8'

Query string	Type	Required	Meaning
endingBefore	string	no	Pagination cursor to fetch the previous page
startingAfter	string	no	Pagination cursor to fetch the next page
limit	integer	no	Objects limit of one page

Response

Returns a list object with event data

## Retrieve events response
{
  "hasMore": false,
  "data": [
    {
        "id": "evt_01DADP4VDPYT9Q8H8SX215WB05",
        "type": "source.updated",
        "...": "..."
    }
  ],
  "object": "list"
}

Retrieve an event

Request

## Retrieve event 
## GET /events/:id
curl "https://api-stg.takemepay.com/v1/events/evt_HxVoR5mYSc-2Ob2rvT2ApQ" \
     -H 'Authorization: Bearer sk_test_your_secret_api_key' \
     -H 'Content-Type: application/json; charset=utf-8'

Argument	Type	Required	Meaning
id	string	yes	Unique identifier of the object

Response

Returns an existent event object.

## Retrieve event response
{
    "id": "evt_HxVoR5mYSc-2Ob2rvT2ApQ",
    "liveMode": false,
    "object": "event",
    "type": "source.created",
    "created": 1556265228475,
    "data": {
        "dataObject": {},
        "previousObject": {}
    }
}

Avaliable Events type

Type	Note
source.created	Source created
source.updated	Source updated. Has previousObject in data
charge.created	Charge created
charge.updated	Charge updated. Has previousObject in data
refund.created	Refund created

Webhooks

Endpoint	Function
POST /webhooks	Create a webhook
GET /webhooks	List all webhooks
GET /webhooks/:id	Retrieve a webhook
DELETE /webhooks/:id	Delete a webhook

Webhooks objects allow you to get notification about Events.

Your endpoints that handling webhooks should return HTTP 200 OK as soon as possible. Events may be send to webhook endpoint more than once. When your server returns error or timeout, events will be send again later with exponential backoff, e.g. after 1/2/4/8 secounds.

## Webhooks
{
    "id": "we_KGUWoFXaQlu3LZqaYPW4Ag",
    "object": "webhook",
    "liveMode": false,
    "enabledEvents": [
        "source.update"
    ],
    "secret": "wesec_svgdAXDfRQqP830Q41GjHg",
    "url": "https://www.example.com/hook",
    "created": 1556265228475
}

The webhook object

Attribute	Type	Meaning
id	string	Unique identifier
object	string	Object's resource type
liveMode	boolean	Flag indicates whether this object is in test mode or live mode
enabledEvents	list	List of enabled event types
secret	string	Secret for sign verification
url	string	Webhook HTTPS endpoint url
created	integer	Created timestamp in Unix epoch milliseconds

Webhook sign verification

Requests posted to your webhook endpoint have a http header TakemePay-Signature. It contains event signature in format "t=timestamp,s=signed_data". signed_data is generated by computing HMAC with the SHA256 hash function on timestamp.payload

To verify a sign:

Extract the timestamp and signatures from the TakemePay-Signature header.
Construct data_to_sign by concatenating timestamp, . and JSON payload(request body).
Compute HMAC SHA256 of data_to_sign, use the webhook's secret as secret cryptographic key.
Compare the computed data_to_sign sign with signed_data.

Create a webhook

Request

## Create webhook
## POST /webhooks
curl -X "POST" "https://api-stg.takemepay.com/v1/webhooks" \
     -H 'Authorization: Bearer sk_test_your_secret_api_key' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
        "enabledEvents": [
            "source.updated"
        ],
        "url": "https://demo.takemepay.com/hook"
    }'

Argument	Type	Required	Meaning
enabledEvents	string	yes	List of enabled event types
url	string	yes	Webhook HTTPS endpoint url

Response

Returns a newly created webhook object.

## Create webhook response
{
    "id": "we_jPkQ2T9QSpe_vidCLEF6FQ",
    "url": "https://demo.takemepay.com/hook",
    "enabledEvents": [
        "source.updated"
    ],
    "liveMode": false,
    "secret": "wesec_QMHzqcm0QzCxIoZXVCu7LA",
    "created": 1557196956000,
    "object": "webhook"
}

Retrieve all webhooks

## Retrieve all webhooks 
## GET /webhooks
curl "https://api-stg.takemepay.com/v1/webhooks" \
     -H 'Authorization: Bearer sk_test_your_secret_api_key' \
     -H 'Content-Type: application/json; charset=utf-8'

Response

Returns a list of webhook objects.

## Retrieve all webhooks response
[
    {
        "id": "we_jPkQ2T9QSpe_vidCLEF6FQ",
        "url": "https://demo.takemepay.com/hook",
        "enabledEvents": [
            "source.updated"
        ],
        "liveMode": false,
        "secret": "wesec_QMHzqcm0QzCxIoZXVCu7LA",
        "created": 1557196956000,
        "object": "webhook"
    }
]

Retrieve a webhook

Request

## Retrieve webhook 
## GET /webhooks/:id
curl "https://api-stg.takemepay.com/v1/webhooks/we_jPkQ2T9QSpe_vidCLEF6FQ" \
     -H 'Authorization: Bearer sk_test_your_secret_api_key' \
     -H 'Content-Type: application/json; charset=utf-8'

Argument	Type	Required	Meaning
id	string	yes	Unique identifier of the object

Response

Returns an existent webhook object.

## Retrieve webhook response
{
    "id": "we_jPkQ2T9QSpe_vidCLEF6FQ",
    "url": "https://demo.takemepay.com/hook",
    "enabledEvents": [
        "source.updated"
    ],
    "liveMode": false,
    "secret": "wesec_QMHzqcm0QzCxIoZXVCu7LA",
    "created": 1557196956000,
    "object": "webhook"
}

Delete a webhook

Request

## Delete webhook 
## DELETE /webhooks/:id
curl -X DELETE "https://api-stg.takemepay.com/v1/webhooks/we_jPkQ2T9QSpe_vidCLEF6FQ" \
     -H 'Authorization: Bearer sk_test_your_secret_api_key' \
     -H 'Content-Type: application/json; charset=utf-8'

Argument	Type	Required	Meaning
id	string	yes	Unique identifier of the object

Response

Returns a webhook object with the deleted id.

## Delete webhook response
{
    "id": "we_jPkQ2T9QSpe_vidCLEF6FQ",
    "url": "https://demo.takemepay.com/hook",
    "enabledEvents": [
        "source.updated"
    ],
    "liveMode": false,
    "secret": "wesec_QMHzqcm0QzCxIoZXVCu7LA",
    "created": 1557196956000,
    "object": "webhook"
}

Errors

The TakeMePay API uses the following standard HTTP codes for errors:

HTTP Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong or missing.
403	Forbidden -- The resource requested is forbidden for current API key. Try to use a different one.
404	Not Found -- The specified resource could not be found.
429	Too Many Requests -- You're requesting too fast. Please slow down.
500	Internal Server Error -- We had a problem with our server. Try again later.

Error response

Error response contains an error body with a error object.

{
  "error": {
    "message": "The requester is not authorized to access the resource.",
    "code": "unauthorized"
  }
}

Attribute	Type	Meaning
message	string	Readable message of error's detail
code	string	Error's code, differs from HTTP code

Error codes

Common specific error codes and suggestions are listed below.

Bad Request

Error code	Suggestion
constraint_violation	Check parameter constraint, e.g., length of string
amount_invalid	Check payment amount, e.g., it should be greater than 0
not_chargeable	Wait until source become chargeable and retry again
method_not_supported	Use supported HTTP method
missing_parameter	Add missed parameter
invalid_format	Check parameter format
media_type_not_supported	Use supported HTTP media type
parse_error	Check request body data, e.g., it should be a valid json

Not Found

Error code	Suggestion
missing_object	Check object id parameter