Payment Service API

General notes

Payment Service API provides some useful and powerful set of api. Initially we started discussion about Shufti's complexity of adding new features, finally we decided to decompose the enterprise monolithic application into small interconnected services based on the Microservices Architecture.

Using Payment Service API

The Payment Service API is the primary way to get data in and out of Shufti's payment service. It's a low-level HTTP-based REST API that you can use to query data, create new banks, manage withdrawals and a variety of other things. This guide explains how to accomplish all these things in the Payment Service API.

The basis

This API is HTTP based JSON API, so it works with any language that has an HTTP library, such as cURL and etc.,

Authentication

Every requests must have to include API access token into its header. Otherwise api server will return 401 Unauthorized as response.

Response type

This API currently supports JSON as return type.

Try it out

When you try this api you have to substitute the following environment variable as of your local env.

{{host}} - Name of api server host.

{{api_token}} - Your API token.

Version

Current stable version is v1

API structures

Bank

Holding the bank account informations.

id integer A unique identifier for the bank
user_id string Owner of this bank
bank_code string The code name of the bank
bank_name string The name of the bank
branch_code string The code name of the branch
branch_name string The name of the branch
account_type integer Type of the account
account_no string Account number
account_name string Account holders name
bank_type integer Type of the bank
japanpost_code_no string Japan post bank code number
japanpost_account_no string Japan post bank account number

Withdrawal 317-456-1395

Holding money transmission logs.

id integer A unique identifier for the withdrawal
bank_id integer Identifier of the bank
amount integer Amount to be transmitted
pay_at date Date of payment
status integer Status of the payment
error_code string Error code received from the bank system
sent_at date Transferred date

API detail

Banks (416) 548-5513

The Banks API supports list, create, edit, view, delete and listing the change history on banks resource. The following examples demonstrate how you would accomplish common tasks with the Banks API.

Get all banks

This request retreive all the bank resources.

curl -X GET -H "Authorization: Bearer {{api_token}}" -H "Accept: application/json" "/{{domain}}/api/v1/banks"
GET /api/v1/banks HTTP/1.1
Host: {{domain}}
Authorization: Bearer {{api_token}}
Accept: application/json
Status200 OK
Cache-Controlno-cache
Connectionkeep-alive
Content-Length664
Content-Typeapplication/json
DateMon, 19 Dec 2016 06:55:04 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining59
{
    "links": {
        "self": "\/\/staging.payment.uluru.jp\/api\/v1\/banks",
        "first": "\/\/staging.payment.uluru.jp\/api\/v1\/banks?page=1",
        "prev": null,
        "next": null,
        "last": "\/\/staging.payment.uluru.jp\/api\/v1\/banks?page=1"
    },
    "data": [
        {
            "type": "banks",
            "id": "1",
            "attributes": {
                "client_id": 1,
                "user_id": 1234,
                "bank_code": "123",
                "bank_name": "Test Bank",
                "branch_name": "Test BRanch",
                "branch_code": "456",
                "account_type": 1,
                "account_no": "7654321",
                "account_name": "Account Holder",
                "bank_type": 1,
                "japanpost_code_no": null,
                "japanpost_account_no": null,
                "created": "2016-12-19 15:54:13",
                "modified": "2016-12-19 15:54:13"
            }
        }
    ],
    "meta": {
        "total": 1,
        "per_page": 15,
        "current_page": 1,
        "last_page": 1
    }
}

Create new bank

Create new bank resource. if the request is done then return the newly created resource's id.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {{api_token}}" -H "Accept: application/json" -d '{
  "data": {
    "type": "banks",
    "attributes": {
      "user_id": 1234,
      "bank_name" : "Test Bank",
      "bank_code" : "123",
      "branch_name" : "Test BRanch",
      "branch_code" : "456",
      "account_type" : 1,
      "account_no" : "7654321",
      "account_name" : "Account Holder",
      "bank_type" : 1
    }
  }
}' "/{{domain}}/api/v1/banks"
POST /api/v1/banks HTTP/1.1
Host: {{domain}}
Content-Type: application/json
Authorization: Bearer {{api_token}}
Accept: application/json

{
  "data": {
    "type": "banks",
    "attributes": {
      "user_id": 1234,
      "bank_name" : "Test Bank",
      "bank_code" : "123",
      "branch_name" : "Test BRanch",
      "branch_code" : "456",
      "account_type" : 1,
      "account_no" : "7654321",
      "account_name" : "Account Holder",
      "bank_type" : 1
    }
  }
}
Status201 Created
Cache-Controlno-cache
Connectionkeep-alive
Content-Length444
Content-Typeapplication/json
DateMon, 19 Dec 2016 06:54:13 GMT
Location/staging.payment.uluru.jp/api/v1/banks/1
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining58
{
    "data": {
        "type": "banks",
        "id": "1",
        "attributes": {
            "client_id": 1,
            "user_id": 1234,
            "bank_code": "123",
            "bank_name": "Test Bank",
            "branch_name": "Test BRanch",
            "branch_code": "456",
            "account_type": 1,
            "account_no": "7654321",
            "account_name": "Account Holder",
            "bank_type": 1,
            "japanpost_code_no": null,
            "japanpost_account_no": null,
            "created": "2016-12-19 15:54:13",
            "modified": "2016-12-19 15:54:13"
        },
        "links": {
            "self": "\/\/staging.payment.uluru.jp\/api\/v1\/banks\/1"
        }
    }
}
Status422 Unprocessable Entity
Cache-Controlno-cache
Connectionkeep-alive
Content-Length119
Content-Typeapplication/json
DateMon, 19 Dec 2016 06:54:36 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining57
{
    "errors": [
        {
            "status": 422,
            "source": {
                "pointer": "\/data\/attributes\/user_id"
            },
            "title": "The user id field is required."
        }
    ]
}

Get a single bank 2073530698

Get single bank resource

curl -X GET -H "Authorization: Bearer {{api_token}}" -H "Accept: application/json" "/{{domain}}/api/v1/banks/1"
GET /api/v1/banks/1 HTTP/1.1
Host: {{domain}}
Authorization: Bearer {{api_token}}
Accept: application/json
Status200 OK
Cache-Controlno-cache
Connectionkeep-alive
Content-Length444
Content-Typeapplication/json
DateMon, 19 Dec 2016 06:55:46 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining59
{
    "links": {
        "self": "\/\/staging.payment.uluru.jp\/api\/v1\/banks\/1"
    },
    "data": {
        "type": "banks",
        "id": "1",
        "attributes": {
            "client_id": 1,
            "user_id": 1234,
            "bank_code": "123",
            "bank_name": "Test Bank",
            "branch_name": "Test BRanch",
            "branch_code": "456",
            "account_type": 1,
            "account_no": "7654321",
            "account_name": "Account Holder",
            "bank_type": 1,
            "japanpost_code_no": null,
            "japanpost_account_no": null,
            "created": "2016-12-19 15:54:13",
            "modified": "2016-12-19 15:54:13"
        }
    }
}
Status404 Not Found
Cache-Controlno-cache
Connectionkeep-alive
Content-Length27
Content-Typeapplication/json
DateMon, 19 Dec 2016 06:55:56 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining58
{
    "errors": [
        {
            "status": 404
        }
    ]
}

Update a bank

Update a bank resource.

curl -X PATCH -H "Content-Type: application/json" -H "Authorization: Bearer {{api_token}}" -H "Accept: application/json" -d '{
  "data": {
    "type": "banks",
    "id":1,
    "attributes": {
      "user_id":391878,
      "bank_name" : "Bank Of Tokyo UFJ",
      "bank_code" : "123",
      "branch_name" : "Kachidoki",
      "branch_code" : "456",
      "account_type" : 1,
      "account_no" : "7654321",
      "account_name" : "カブシキカイシャウルル",
      "bank_type" : 1
    }
  }
}' "/{{domain}}/api/v1/banks/1"
PATCH /api/v1/banks/1 HTTP/1.1
Host: {{domain}}
Content-Type: application/json
Authorization: Bearer {{api_token}}
Accept: application/json

{
  "data": {
    "type": "banks",
    "id":1,
    "attributes": {
      "user_id":391878,
      "bank_name" : "Bank Of Tokyo UFJ",
      "bank_code" : "123",
      "branch_name" : "Kachidoki",
      "branch_code" : "456",
      "account_type" : 1,
      "account_no" : "7654321",
      "account_name" : "カブシキカイシャウルル",
      "bank_type" : 1
    }
  }
}
Status200 OK
Cache-Controlno-cache
Connectionkeep-alive
Content-Length504
Content-Typeapplication/json
DateMon, 19 Dec 2016 06:56:32 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining59
{
    "links": {
        "self": "\/\/staging.payment.uluru.jp\/api\/v1\/banks\/1"
    },
    "data": {
        "type": "banks",
        "id": "1",
        "attributes": {
            "client_id": 1,
            "user_id": 391878,
            "bank_code": "123",
            "bank_name": "Bank Of Tokyo UFJ",
            "branch_name": "Kachidoki",
            "branch_code": "456",
            "account_type": 1,
            "account_no": "7654321",
            "account_name": "\u30ab\u30d6\u30b7\u30ad\u30ab\u30a4\u30b7\u30e3\u30a6\u30eb\u30eb",
            "bank_type": 1,
            "japanpost_code_no": null,
            "japanpost_account_no": null,
            "created": "2016-12-19 15:54:13",
            "modified": "2016-12-19 15:56:32"
        }
    }
}
Status422 Unprocessable Entity
Cache-Controlno-cache
Connectionkeep-alive
Content-Length119
Content-Typeapplication/json
DateMon, 19 Dec 2016 06:56:44 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining58
{
    "errors": [
        {
            "status": 422,
            "source": {
                "pointer": "\/data\/attributes\/user_id"
            },
            "title": "The user id field is required."
        }
    ]
}

Delete a bank (760) 663-8727

Delete a bank resource.

curl -X DELETE -H "Authorization: Bearer {{api_token}}" "/{{domain}}/api/v1/banks/1"
DELETE /api/v1/banks/1 HTTP/1.1
Host: {{domain}}
Authorization: Bearer {{api_token}}
Status204 No Content
Cache-Controlno-cache
Connectionkeep-alive
Content-Typetext/html; charset=UTF-8
DateMon, 19 Dec 2016 06:57:12 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining59
Status404 Not Found
Cache-Controlno-cache
Connectionkeep-alive
Content-Length27
Content-Typeapplication/json
DateMon, 19 Dec 2016 06:57:32 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining58
{
    "errors": [
        {
            "status": 404
        }
    ]
}

Change History

Retrieve change logs of a bank resource.

curl -X GET -H "Authorization: Bearer {{api_token}}" -H "Accept: application/json" "/{{domain}}/api/v1/banks/1/history"
GET /api/v1/banks/1/history HTTP/1.1
Host: {{domain}}
Authorization: Bearer {{api_token}}
Accept: application/json
Status200 OK
Cache-Controlno-cache
Connectionkeep-alive
Content-Typeapplication/json
DateMon, 19 Dec 2016 06:57:45 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining59
transfer-encodingchunked
[
    {
        "id": "a038f9ba-adca-4e24-bb70-5193ad9cdfd1",
        "type": "deleted",
        "auditable_id": 1,
        "auditable_type": "App\\Bank",
        "old": {
            "id": 1,
            "client_id": 1,
            "user_id": 391878,
            "bank_code": "123",
            "bank_name": "Bank Of Tokyo UFJ",
            "branch_name": "Kachidoki",
            "branch_code": "456",
            "account_type": 1,
            "account_no": "7654321",
            "account_name": "\u30ab\u30d6\u30b7\u30ad\u30ab\u30a4\u30b7\u30e3\u30a6\u30eb\u30eb",
            "bank_type": 1,
            "japanpost_code_no": null,
            "japanpost_account_no": null,
            "deleted_at": "2016-12-19 15:57:12"
        },
        "new": [],
        "user_id": "1",
        "route": "\/\/staging.payment.uluru.jp\/api\/v1\/banks\/1",
        "ip_address": "172.31.12.163",
        "created_at": "2016-12-19 15:57:12",
        "custom_message": "Not defined custom message!",
        "custom_fields": [],
        "elapsed_time": "33 seconds ago"
    },
    {
        "id": "e7d7ac39-d7b6-43a6-ac90-f0ed92e36400",
        "type": "updated",
        "auditable_id": 1,
        "auditable_type": "App\\Bank",
        "old": {
            "user_id": 1234,
            "bank_name": "Test Bank",
            "branch_name": "Test BRanch",
            "account_name": "Account Holder"
        },
        "new": {
            "user_id": 391878,
            "bank_name": "Bank Of Tokyo UFJ",
            "branch_name": "Kachidoki",
            "account_name": "\u30ab\u30d6\u30b7\u30ad\u30ab\u30a4\u30b7\u30e3\u30a6\u30eb\u30eb"
        },
        "user_id": "1",
        "route": "\/\/staging.payment.uluru.jp\/api\/v1\/banks\/1",
        "ip_address": "172.31.12.163",
        "created_at": "2016-12-19 15:56:32",
        "custom_message": "Not defined custom message!",
        "custom_fields": [],
        "elapsed_time": "1 minute ago"
    },
    {
        "id": "ac009c1c-6e1d-40d1-a971-e3a172633612",
        "type": "created",
        "auditable_id": 1,
        "auditable_type": "App\\Bank",
        "old": [],
        "new": {
            "user_id": 1234,
            "bank_name": "Test Bank",
            "bank_code": "123",
            "branch_name": "Test BRanch",
            "branch_code": "456",
            "account_type": 1,
            "account_no": "7654321",
            "account_name": "Account Holder",
            "bank_type": 1,
            "client_id": 1
        },
        "user_id": "1",
        "route": "\/\/staging.payment.uluru.jp\/api\/v1\/banks",
        "ip_address": "172.31.12.163",
        "created_at": "2016-12-19 15:54:13",
        "custom_message": "Not defined custom message!",
        "custom_fields": [],
        "elapsed_time": "3 minutes ago"
    }
]

Withdrawals 7347671151

Withdrawals API

Get all withdrawals 2259278784

Get all withdrawal resources.

curl -X GET -H "Authorization: Bearer {{api_token}}" -H "Accept: application/json" "/{{domain}}/api/v1/withdrawals"
GET /api/v1/withdrawals HTTP/1.1
Host: {{domain}}
Authorization: Bearer {{api_token}}
Accept: application/json
Status200 OK
Cache-Controlno-cache
Connectionkeep-alive
Content-Length319
Content-Typeapplication/json
DateMon, 19 Dec 2016 06:58:25 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining59
{
    "links": {
        "self": "\/\/staging.payment.uluru.jp\/api\/v1\/withdrawals",
        "first": "\/\/staging.payment.uluru.jp\/api\/v1\/withdrawals?page=1",
        "prev": null,
        "next": null,
        "last": "\/\/staging.payment.uluru.jp\/api\/v1\/withdrawals?page=1"
    },
    "data": [],
    "meta": {
        "total": 0,
        "per_page": 15,
        "current_page": 1,
        "last_page": 0
    }
}

Create new withdrawal

Create new withdrawal resource.

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {{api_token}}" -H "Accept: application/json" -d '{
  	"data": {
    	"type": "withdrawals",
    	"attributes": {
    		"amount" : 100,
    		"pay_at": "2016-12-22"
		}
	}
}' "/{{domain}}/api/v1/banks/1/withdrawals"
POST /api/v1/banks/1/withdrawals HTTP/1.1
Host: {{domain}}
Content-Type: application/json
Authorization: Bearer {{api_token}}
Accept: application/json

{
  	"data": {
    	"type": "withdrawals",
    	"attributes": {
    		"amount" : 100,
    		"pay_at": "2016-12-22"
		}
	}
}
Status201 Created
Cache-Controlno-cache
Connectionkeep-alive
Content-Length286
Content-Typeapplication/json
DateMon, 19 Dec 2016 06:58:52 GMT
Location/staging.payment.uluru.jp/api/v1/withdrawals/1
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining59
{
    "data": {
        "type": "withdrawals",
        "id": "1",
        "attributes": {
            "bank_id": 1,
            "amount": 100,
            "status": 0,
            "error_code": null,
            "pay_at": "2016-12-22",
            "sent": null,
            "created": "2016-12-19 15:58:52",
            "modified": "2016-12-19 15:58:52"
        },
        "links": {
            "self": "\/\/staging.payment.uluru.jp\/api\/v1\/withdrawals\/1"
        }
    }
}
Status404 Not Found
Cache-Controlno-cache
Connectionkeep-alive
Content-Length27
Content-Typeapplication/json
DateMon, 19 Dec 2016 06:59:10 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining58
{
    "errors": [
        {
            "status": 404
        }
    ]
}
Status422 Unprocessable Entity
Cache-Controlno-cache
Connectionkeep-alive
Content-Length131
Content-Typeapplication/json
DateMon, 19 Dec 2016 06:59:35 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining57
{
    "errors": [
        {
            "status": 422,
            "source": {
                "pointer": "\/data\/attributes\/pay_at"
            },
            "title": "The pay at must be a date after 2016-12-18."
        }
    ]
}

Update a withdrawal

Update a withdrawal resource.

curl -X PATCH -H "Content-Type: application/json" -H "Authorization: Bearer {{api_token}}" -H "Accept: application/json" -d '{
  "data": {
    "type": "withdrawals",
    "id": 1,
    "attributes": {
      "status" : 3
    }
  }
}' "/{{domain}}/api/v1/banks/1/withdrawals/1"
PATCH /api/v1/banks/1/withdrawals/1 HTTP/1.1
Host: {{domain}}
Content-Type: application/json
Authorization: Bearer {{api_token}}
Accept: application/json

{
  "data": {
    "type": "withdrawals",
    "id": 1,
    "attributes": {
      "status" : 3
    }
  }
}
Status200 OK
Cache-Controlno-cache
Connectionkeep-alive
Content-Length286
Content-Typeapplication/json
DateMon, 19 Dec 2016 07:00:14 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining58
{
    "links": {
        "self": "\/\/staging.payment.uluru.jp\/api\/v1\/withdrawals\/1"
    },
    "data": {
        "type": "withdrawals",
        "id": "1",
        "attributes": {
            "bank_id": 1,
            "amount": 100,
            "status": 3,
            "error_code": null,
            "pay_at": "2016-12-22",
            "sent": null,
            "created": "2016-12-19 15:58:52",
            "modified": "2016-12-19 16:00:14"
        }
    }
}
Status422 Unprocessable Entity
Cache-Controlno-cache
Connectionkeep-alive
Content-Length119
Content-Typeapplication/json
DateMon, 19 Dec 2016 07:00:27 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining57
{
    "errors": [
        {
            "status": 422,
            "source": {
                "pointer": "\/data\/attributes\/status"
            },
            "title": "The selected status is invalid."
        }
    ]
}

Delete a withdrawal 636-447-7515

Delete a withdrawal resource

curl -X DELETE -H "Authorization: Bearer {{api_token}}" "/{{domain}}/api/v1/banks/1/withdrawals/1"
DELETE /api/v1/banks/1/withdrawals/1 HTTP/1.1
Host: {{domain}}
Authorization: Bearer {{api_token}}
Status204 No Content
Cache-Controlno-cache
Connectionkeep-alive
Content-Typetext/html; charset=UTF-8
DateMon, 19 Dec 2016 07:02:40 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining59
Status404 Not Found
Cache-Controlno-cache
Connectionkeep-alive
Content-Length27
Content-Typeapplication/json
DateMon, 19 Dec 2016 07:02:59 GMT
Servernginx
X-RateLimit-Limit60
X-RateLimit-Remaining58
{
    "errors": [
        {
            "status": 404
        }
    ]
}