WOI | Partner Integration Documentation

Technical Documentation SNAP

Overview of OpenAPI for BI SNAP Use Case in WOI

Method	Endpoint	Usage
POST	`.../v1.0/access-token/b2b`	Generate Access Token (B2B)
POST	`.../v1.0/access-token/b2b2c`	Account Binding
POST	`.../v1.0/registration-account-unbinding`	Account Unbinding
POST	`.../v1.0/balance-inquiry`	Balance Inquiry
POST	`.../v1.0/debit/payment-host-to-host`	Direct Debit
POST	`.../v1.0/qr/qr-mpm-generate`	QRIS MPM Acquiring

Generate System Token (B2B)

Partner with client-specific use cases (non-user-related use-case) can use the below API to generate system tokens.

Before generating the token, partners are requested to address this as a requirement, so WOI can configure the necessary.

Endpoint: .../{version}/access-token/b2b

Header Request

Parameter	Data Type	Mandatory	Description
X-CLIENT-KEY	String	M	Client’s client_id (PJP Name) (given at completion registration process )
Content-Type	String	M	String represents indicate the media type of the resource (e.g. application/json, application/pdf)
X-SIGNATURE	String	M	Using Asymmetric Signature
X-TIMESTAMP	String	M	Client's current local time in yyyy-MM-ddTHH:mm:ss.SSSTZD format

Body Request

Parameter	Data Type	Mandatory	Description
grantType	String	M	"client_credentials”: The client can request an access token using only its client credentials (or other supported means of authentication) when the client is requesting access to the protected resources under its control

Body Response

Parameter	Data Type	Description
responseCode	String	Refer to standar data dan spesifikasi teknis part 6 (Response Code).If access token failed to generate, this value must be filled.
responseMessage	String	Refer to standar data dan spesifikasi teknis part 6 (Response Message)*If access token failed to generate, this value must be filled*.
accessToken	String (2048)	A string representing an authorizationissued to the client that used to accessprotected resources
tokenType	String	The access token type provides the client with the information required to successfully utilize the access token to makea protected resource request (along with type-specific attributes) Token Type Value: "Bearers”: includes the access token String in the request "Mac": issuing a Message Authentication Code (MAC) key together with the access token that is used to sign certain components of the HTTP requests
expiresIn	String	Session expiry in seconds

Sample Request


                curl --location --request POST 'https://devwoi.jatis.com/v1.0/access-token/b2b' \

                    --header 'x-client-key: test' \

                    --header 'Content-Type: application/json' \

                    --header 'X-Signature: 14fc9b92ce30559b3db75987b0150890e2680fe5dc8e2eda9ed77304603dcf0670f41ff1de1b3d5a79e417f39391abb694f41028b1a425f2d40e7eccf988a5f281f96afea63a8cfe7f01938b7d67a76070b7fb3a7c6cdfe1f94e6e98e502db8cdc8a7db0aa08186ae44c28197a3b2f66dd8170d0a1c848f0a424a6d857ecbf8337cefa7120b5e4a04bd52f4cc9a6ae5a3bd9c8125227b5a259cd03ed7c4ea3afef9f147f3d73b99b3c1e6df68011b485ed0c177133c92d8cce913f14bb10da8223783c8b94b0c0a65b07fdeac0f3687d86a95bb4389f4e15b5679119dee0679823dd8db5e28af728c32600d1a2af48871ec2134dc5ac6ede056fb7d557d5d824' \

                    --header 'x-Timestamp: 2022-08-02T02:03:08.123Z' \

                    --data-raw '{

                            "grantType" : "client_credentials"

                            }'

Sample Response


                {

                    "responseCode": "2007300",

                    "responseMessage": "Success",

                    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb2RlaGFzaCI6IlptVTRORGt5WVRnM01EZ3lOR1JpWmprMU5HSTBZakE1TURVMU1UWmhOV0kiLCJyYW5kb20iOiJOalF3TXpFMk5RIiwidmVyc2lvbiI6MX0.Wo5-5jM07X6Ft9UjZx0u2H9egmu76VwXoZzxcB_noSQ",

                    "tokenType": "Bearer",

                    "expiresIn": "900"

                }

Transaction API Headers

All the APIs mentioned are to follow the standard header format mentioned here, unless stated otherwise

Parameters	Description	Attribute	Example
Content-type	String represents indicating the media type of the resource	Mandatory	application/json,application/pdf
Authorization	Represents access_token of a request;string starts with keyword “Bearer ”followed by accessToken (e.g. BearereyJraWQiOi...JzcIiwiY)	No Need For Request B2B Access Token API	Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a
X-PARTNER-ID	Client's client_id.	Mandatory	oamerchantg
X-TIMESTAMP	Client's current local time in yyyyMMddTHH:mm:ss.SSSTZD format	Mandatory
X-SIGNATURE	Use Asymmetric for Token request Use Symmetric for all transaction header	Mandatory	Please check Signature Section
X-DEVICE-ID	Device identification on which the API services are currently being accessed by the end-user (customer)	Optional
X-EXTERNAL-ID	Unique ID to avoid duplication. ID reset for every 24 hours	Mandatory
CHANNEL-ID	PJP’s channel id Device identification on which the API services is currently being accessed by the end user (customer)	Optional

Error Code

Here is the list of authentication related common error codes that can be returned throughout all APIs. Please note that the “XX” in the middle of the error code will follow the respective service code of the API. Except for the APIs that are not part of BISNAP, but are using the same BISNAP authentication mechanism, for this kind of API “XX” will stay as it is.

HTTP Code	Error Code	Error Message (Indonesian)
401	401XX00	Unauthorized. [reason]
401	401XX01	Invalid Token:Anda Tidak Memiliki Akses

Sample Response


                    {
                    
   "responseCode": "4013700",
                    
   "responseMessage": "Unauthorized. No Interface Definition: Timestamp."
                    
}


                    {
                    
   "responseCode": "4013700",
                    
   "responseMessage": "Unauthorized. Signature Failed"
                    
}

Signature Asymmetric

Signature asymmetric is used by WOI to verify that your access token request is not altered by attackers.

Generate Signature Asymmetric for Header of Access Token B2B / B2B2C

SHA256withRSA is used to generate the signature with your Private Key as the key.

X-SIGNATURE = SHA256withRSA(PrivateKey, StringToSign)

The StringToSign will be a colon-separated list derived from some request data as below:


                StringToSign = HTTPMethod + ”:“+ EndpointUrl +":“ + Lowercase(HexEncode(SHA-256(minify(RequestBody)))) + ":“ + TimeStamp

Signature Symmetric

Signature is used to verify that your open API service request is not altered by attackers.

Generate Signature Symmetric

SHA-512 HMAC is used to generate the signature with your Client Secret as the key.

X-SIGNATURE = HMAC-SHA512(ClientSecret, StringToSign)

The StringToSign will be a colon-separated list derived from some request data as below :


                stringToSign = HTTPMethod + ”:“+ EndpointUrl +":"+ AccessToken + ":“+ Lowercase(HexEncode(SHA-256(minify(RequestBody)))) + ":“ + TimeStamp

Notes:

Endpoint URL complete including all parameters on URL related
For parameters minify (Request Body), in case there is no Request Body then use the empty string

How to Generate PKCS1 Private Key and Public Key

Generate Private Key:


                openssl genrsa -out private.pem 4096

Generate PKCS1 Public Key:


                openssl rsa -in private.pem -RSAPublicKey_out -out public.pem

Error Code

HTPP Code	Error Code	Error Message (Indonesian)
401	4017300	Unauthorized. [HMAC mismatch]
400	4007301	Invalid timestamp format [X-TIMESTAMP]
400	4017300	Invalid field format [clientId/clientSecret/grant_type]

Account Binding

Diagram

This API is for initiating process binding. Merchant’s backend will generate parameters to be hit to WOI Get Auth Code API, then WOI will return with a webview URL. Merchant application need to open this webview to continue the binding process.

Your request must contain the following information:

Request Body

Parameter	Data Type	Mandatory	Description
grantType	String (64)	M	Apply token request type. The values are AUTHORIZATION_CODE or REFRESH_TOKEN
authCode	String (256)	C	An authorization code which the caller get from API Get OAuth 2.0 URL
refreshToken	String (512)	C	This token is used for refresh session if existing token has been expired
additionalInfo	String (64)	O	Additional information

Response Body

Parameter	Data Type	Description
responseCode	String	Response code
responseMessage	String	Response description
accessToken	String	B2B2C Access Token
tokenType	String	Token Type
accessTokenExpiryTime	String
refreshToken	String
refreshTokenExpiryTime	String
additionalInfo	Object
>userInfo	Object
>>publicUserId	String

Sample Request


                {

                    "grantType": "AUTHORIZATION_CODE",,

                    "authCode": "ABC3821738137123",

                    "refreshToken": "", 

                    "additionalInfo": {}

                }

Sample Response


                {

                        "responseCode": "2007400",

                        "responseMessage": "Successful",

                        "accessToken": "SQoHkw1tSfWsULjf3qrWpPqimAQi6IxcgmvO4200",

                        "tokenType": "Bearer",

                        "accessTokenExpiryTime": "2031-11-02T11:31:19+07:00",

                        "refreshToken": "NEcnzX7Aq2vv5Ot08ZDSmCzfO4aEWhnWTpbf4200",

                        "refreshTokenExpiryTime": "2031-11-02T11:31:19+07:00",

                        "additionalInfo": {

                                "userInfo": {

                                    "publicUserId": "21779009320193133"

                                }

                        }

                }

Account Unbinding

This API will be used by Merchants to Initiate Unbinding Customer's Account

Diagram

Your request must contain the following information:

Request Body

Parameter	Data Type	Mandatory	Description
merchantId	String (64)	M	Merchant identifier that is unique per each merchant
subMerchantId	String (31)	O	Information of sub merchant identifier
partnerReferenceNo	String (64)	O	Unique transaction identifier on partner system which assigned to each transaction
linkId	String (24)	O	Information of link identifier
tokenId	String (128)	O	Information of token identifier
additionalInfo	Object	O	Additional information
>accessToken	String (512)	M	Contains customer token, which has been obtained from binding process

Response Body

Parameter	Data Type	Description
responseCode	String	Response code
responseMessage	String	Response description
referenceNo	String	Transaction identifier on service provider system. Must be filled upon successful transactions
partnerReferenceNo	String	Transaction identifier on service consumer system
merchantId	String	Merchant identifier that is unique per each merchant
subMerchantId	String	Information of sub merchant identifier
linkId	String	Information of link identifier
unlinkResult	String	Result of unlinking process

Sample Request


                {

                        "partnerReferenceNo": "2020102900000000000001",

                        "linkId": "abcd1234efgh5678ijkl9012",

                        "merchantId": "23489182303312",

                        "subMerchantId": "23489182303312",

                        "tokenId": "Aeox320xvijwefop10",

                        "additionalInfo": {

                                "accessToken": "fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a"

                            }

                }

Sample Response


                {

                        "responseCode": "2000900",

                        "responseMessage": "Successful",

                        "referenceNo": "2020102977770000000009",

                        "partnerReferenceNo": "2020102900000000000001",

                        "merchantId": "23489182303312",

                        "subMerchantId": "23489182303312",

                        "linkId": "abcd1234efgh5678ijkl9012",

                        "unlinkResult": "success",

                        "additionalInfo": {}

                }

Balance Inquiry

This API will be used by Merchants to get Customer's balance information. This requires Account Binding process

Diagram

Request Body

Parameter	Data Type	Mandatory	Description
partnerReferenceNo	String (64)	M	Merchant identifier that is unique per each merchant
additionalInfo	Object	O	Additional information
>accessToken	String (512)	M	Contains customer token, which has been obtained from binding process

Response Body

Parameter	Data Type	Description
responseCode	String	Response code
responseMesage	String	Response description
account	String
loginId	String
balance	String	Customer's Balance

Sample Request


                {

                        "partnerReferenceNo": "2020102900000000000001",

                        "additionalInfo": {

                            "accessToken": "fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a"

                        }

                }

Sample Response


                {

                        "responseCode": "2001100",

                        "responseMessage": "Successful",

                        "account": "081110008027",

                        "loginId": "00000000000001",

                        "balance": "100000.00"

                }

Direct Debit

This API will be used by Merchants to debit customer's balance

Request Body

Parameter	Data Type	Mandatory	Description
partnerReferenceNo	String (64)	M	Merchant identifier that is unique per each merchant
merchantId	String (64)	M	Merchant identifier that is unique per each merchant
partnerReferenceNo	String (64)	M	Merchant identifier that is unique per each merchant
amount	Object	M
>value	String (19)	M	Value of amount. Following ISO-4217, for IDR the value includes 2 decimal digits separated with point e.g., IDR 10.000,- will be placed with 10000.00
>currency	String (3)	M	Currency
additionalInfo	Object	O	Additional information
>accessToken	String (512)	M	Contains customer token, which has been obtained from binding process

Response Body

Parameter	Data Type	Description
responseCode	String	Response code
responseMesage	String	Response description
referenceNo	String
partnerReferenceNo	String
webRedirectUrl	String	Webview URL for direct debit
additionalInfo	Object

Sample Request


                    {

                        "partnerReferenceNo": "2020102900000000000001",

                        "merchantId": "abcd1234efgh5678ijkl9012",

                        "amount": {

                            "value": "12345678.00",

                            "currency": "IDR"

                        },

                        "additionalInfo": {

                            "accessToken": "fa8sjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a"

                        }

                    }

Sample Response


                    {

                        "responseCode": "2005400",

                        "responseMessage": "Successful",

                        "referenceNo": "2020102977770000000009",

                        "partnerReferenceNo": "2020102900000000000001",

                        "webRedirectUrl": "https://pjsp.com/universal?bizNo=REF993883&...",

                        "additionalInfo":{}

                    }

QRIS MPM Acquiring

This API will be used by Merchants to produce MPM QRIS, which will be shown to Customer

Request Body

Parameter	Data Type	Mandatory	Description
merchantId	String (64)	M	Merchant identifier that is unique per each merchant
partnerReferenceNo	String (64)	M	Merchant identifier that is unique per each merchant
amount	Object	M
>value	String (19)	M	Value of amount. Following ISO-4217, for IDR the value includes 2 decimal digits separated with point e.g., IDR 10.000,- will be placed with 10000.00
>currency	String (3)	M	Currency

Response Body

Parameter	Data Type	Description
responseCode	String	Response code
responseMesage	String	Response description
partnerReferenceNo	String
qrContent	String	String of QRIS which need to be parsed into QR Image
merchantName	String	Name of merchant
additionalInfo	Object

Sample Request


                    {

                        "merchantId": "23489182303312",

                        "partnerReferenceNo": "239850918204981205970",

                        "amount": {

                            "value": "123000.00",

                            "currency": "IDR"

                        }

                    }

Sample Response


                    {

                        "responseCode": "2005800",

                        "responseMessage": "Successful",

                        "partnerReferenceNo": "2020102977770000000009",

                        "qrContent": "00020101021226670021COM.INDIVARAGROUP.WWW011893600844300117931302090011793130303UMI52045611530336054061230005802ID550202560435005911Perdiansyah6015Kota Jakarta Ba6105112706304898F",

                        "merchantName": "Perdiansyah"

                    }

WOI Payment API

Technical Documentation SNAP

Generate System Token (B2B)

Header Request

Body Request

Body Response

Sample Request

Sample Response

Transaction API Headers

Error Code

Sample Response

Signature Asymmetric

Generate Signature Asymmetric for Header of Access Token B2B / B2B2C

Signature Symmetric

Generate Signature Symmetric

How to Generate PKCS1 Private Key and Public Key

Error Code

Account Binding

Diagram

Request Body

Response Body

Sample Request

Sample Response

Account Unbinding

Diagram

Request Body

Response Body

Sample Request

Sample Response

Balance Inquiry

Diagram

Request Body

Response Body

Sample Request

Sample Response

Direct Debit

Request Body

Response Body

Sample Request

Sample Response

QRIS MPM Acquiring

Request Body

Response Body

Sample Request

Sample Response