YUKK Payment Gateway

Technical Documentation
ver 1.1.3
YUKK Payment Integration – API Documentation

Content
Pre-requisite
Let’s Get Started! 3
API Technical Flow 3
Get Access Token 4
APIs
Get All Payment Channels 5
Request Payment 7
Request VA (via API) 9
Check Payment Status 10

Webhook
Webhook Status Notification 11
JSON Examples 12
HTTP Response Code 15
Other Information 15
Contact 15

Version Note

1.0.1: Define required fields in API Request Payment; Remove `cc_installment_month` in object payment;
Add more payment status to be sent to partner: WAITING, CANCELED; Add `va_number` in response
API Check Payment Status and Webhook Payment Notification; Add information on webhook hit
mechanism if not successfully hit (hit 3 times with an interval of 1 minutes)

1.0.2: Add testing credentials

1.0.3: Change key `signature-key` in headers webhook to `signature`; Define all payment status in API
Check Payment Status; Update payment status that can be send to callback url and webhook notification;
Update JSON webhook, API Request Payment, and add API Check Payment Status in JSON Example;
Change key `va_number` to `va` and change type from string to object in webhook; Add key `va` as an
object in API Request Payment; Remove `qris` and `expires_in` from API Request Payment; Add `token`
and `redirect_url` in response result of API Check Payment Status; Change webhook hit mechanism if not
successfully hit; Add Version Note; Add one step in Let’s Get Started for VA

1.1.0: Change language to English; Add Request VA (via API) with its http response example

1.1.1: Add payment expiration parameter in API Request Payment `va.expires_in` to customize payment
expiration time; Add `expired_at` in Webhook and API Response Check Payment Status

1.1.2: Add Testing Credentials for VA Static; Fix webhook body; Add user-device in header API get all
payment channels and API request payment; Add `session_timeout` in body API request payment and
Payment Channel Timeout information; Update retry webhook mechanism

1.1.3: Update testing credentials information to use sandbox credentials

2
YUKK Payment Integration – API Documentation

Pre-requisite________________________________________
Let’s Get Started!
Here are the steps to get started before you can access Yukk Payment Gateway API:
1. If you are using Virtual Account as one of your payment channels, inform to Yukk
operational team regarding your Virtual Account type, which explains below:
a. Fixed type: A fixed 16 digit VA number where the first 5 digit is bank code, the
next 3 digit is provider code, the last 8 digit is a predetermined account ID
(account_ID) which should be sent via API Request Payment,
b. Dynamic type: A dynamic VA number which will be generated by system.
2. Ask our operational team to send you these credentials required for your deployment
process: (Note: For testing purpose, please check Other Information on page 15)
a. Partner credentials, consist of unique client_id and client_secret. These
credentials are used in API Get Access Token to retrieve access token once,
then the same access token need to be included in every header every time API
in this documentation is accessed.
b. Merchant credentials, or MID. For partners who have more than one merchant
(for settlement and disbursement purpose), they need to register every merchant
and get one MID each. The MID need to also be included in every header every
time API in this documentation is accessed. Otherwise, you can use only one
MID for every APIs.
3. Prepare two URLs: notification_url for you to get complete payment status
notification, and callback_url for the system to send status and to redirect back to
your page.

Technical Flow
Pictured below is the end-to-end technical flow of how to use Yukk Payment Gateway API after
retrieving access token.

3
YUKK Payment Integration – API Documentation

Get Access Token

Request this API once to get access token and save the token for the next use.

HTTP Request
Method: POST
Endpoint: /api/oauth/token
Headers
Content-Type: application/json
Accept: application/json
Body
Parameter Type Description Value
grant_type string A constant grant type “client_credentials”
client_id number The given client_id {client_id}
client_secret string The given client_secret {client_secret }

HTTP Response
Parameter Type Description
time number Response time (in
milliseconds)
status_ number HTTP Status Code
code
status_ string Status Message
message
result object Parameter Type Description Value
token_type string A constant token type “Bearer”
expires_ number Token expiry time (in
in seconds)
access_ string The access token
token

4
YUKK Payment Integration – API Documentation

APIs________________________________________________
Get All Payment Channels
Request this API to get every active payment channel based on the MID you use.

HTTP Request
Method: GET
Endpoint: api/payment-channels
Headers
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token}
MID: {MID}
User-device: “MOBILE” / “DESKTOP” //to return device-compatible payment channel
Query String
Parameter Type Description Value
grouping integer Boolean of settings to whether 0 = FALSE
enable categorization in 1 = TRUE
payment channels or not
(See JSON Grouping
Example)

HTTP Response (Grouping == 0)

Parameter Type Description Value
time number Response time (in milliseconds)
status_ number HTTP Status Code
code
status_ string Status Message
message
result object Parameter Type Description Value
code string Payment
channel code
used to identify
payment type
name string Payment
channel name
image_url string URL logo
(png/jpg/jpeg)
of payment
channel
category object Parameter Type Description
code string Payment category
code
name string Payment category
name

5
YUKK Payment Integration – API Documentation

HTTP Response (Grouping == 1)

Parameter Type Description Value
time number Response time (in milliseconds)
status_ number HTTP Status Code
code
status_ string Status Message
message
result object Parameter Type Description Value
name string Payment
category
name
code string Payment
category
code
payment_channels Parameter Type Description
code string Payment
channel code
used to identify
payment type
name string Payment
channel name
image_url string URL logo
(png/jpg/jpeg)
of payment
channel

6
YUKK Payment Integration – API Documentation

Request Payment
Request this API to conduct an instant payment using the payment channel of choice. System
will send redirect_url, a URL to redirect the the customer to Yukk Payment Gateway
webpage.

HTTP Request
Method: POST
Endpoint: /api/transactions/request-payment
Headers
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token}
MID: {MID}
User-device: “MOBILE” / “DESKTOP” //to return device-compatible payment channel
Body
Parameter Type Description
request_time * timestamp Payment request time
payment * object Parameter MOC Type Description
pmt_channel_code M string Payment
channel code
of choice
va object Parameter MOC Type Description
account_id C string The last 8 digit of VA
number (for Fixed type
only)
expires_in O integer Set payment expiration (in
seconds)
order_details * object Parameter MOC Type Description
order _id M string Partner order ID
amount M integer Total amount paid by the
customer, including shipping
fee, tax, and other fees
shipping_fee O integer Shipping fee amount
customer * object Parameter MOC Type Description
name M string Customer full name
phone M string Customer phone number
email M string Customer email
billing object Parameter MOC Type Description
name O string Customer full name
phone O string Customer phone number
email O string Customer email
address O string Customer address
city O string Customer city address
state O string Customer province address
country O string Customer country address
postal_code O string Customer postal code
address
callback_url string Callback URL (see Parameter Callback URL)
notification_url string Notification URL
session_timeout Integer Overall timeout required to complete payment in one
session, including timeout for each payment channel (See
Payment Channel Timeout)
E.g: If you fill 1800 seconds for session_timeout and the
payment channel timeout is 300 seconds, then:
1. For webpage, the user needs to confirm the payment
within 1500 seconds in the webpage, and
2. For API Request VA, you need to hit the API within 1500
seconds before it is expired
notes string Other notes if necessary

7
YUKK Payment Integration – API Documentation

HTTP Response
Parameter Type Description
time number Response time (in milliseconds)
status_ number HTTP Status Code
code
status_ string Status Message
message
result object Parameter Type Description Value
redirect_url string Redirect URL
token string Token to initiate webpage
session

Validasi
Amount of order_details.amount >= External MDR + Partner fee (shipping)
If the validation is not matched, error response 400 will show: “Nominal transaksi minimum tidak
mencukupi” (Insufficient minimum transaction amount)

Parameter of Callback URL

Method: POST

Parameter Type Description Value

request_at datetime Payment request time
code string Yukk transaction code
order_id string Partner transaction
code
pmt_channel_code string Payment channel code
va_number string VA number (if using VA
payment channel)
amount integer Total amount paid by
the customer
status string Payment status that will SUCCESS / WAITING / FAILED
be sent to callback url / CANCELED

Payment Channel Timeout

Payment Channel Timeout (in seconds)

OVO 60

CC 330

VA 86400 (default)
can be customized by prompt in key
va.expires_in

8
YUKK Payment Integration – API Documentation

Request VA (via API)

Request this API after you request API Request Payment when your business process does not
require your customer to make the payment in an instant, and only need to get Virtual Account
number.

HTTP Request
Method: POST
Endpoint: /api/transactions/{payment_token}/pay
E.g:
/transactions/YUKK:eyJpdiI6IjVXZDRzdDlObHNNd2pNeG10NEUwOFE9PSIsInZhbHVlIjoiTTVr
T0dPL1ZHMUdhalR3cDl1bG0vTGdvY3EwNTR5VFcrY2REcWJaK2x5dz0iLCJtYWMiOiJhYTZk
NDU4ODEwNzNjZGZhZDA3NjgxYTJjMTZmMmQxYmU0ODI1NjQzNGNjYWRkMWFkMmM4Yz
k3YzVmOGU5OWUyIiwidGFnIjoiIn0=/pay
Headers
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token}
MID: {MID}
Body
-

HTTP Response
Parameter Type Description
time number Response time (in milliseconds)
status_ number HTTP Status Code
code
status_ string Status Message
message
result object Parameter Type Description Value
va object Parameter Type Description
number string Virtual Account
number
expired_at datetime Expiry time of VA
number (default
value is 24hours
after request date)

9
YUKK Payment Integration – API Documentation

Check Payment Status

Request this API to check the last updated payment status of your transaction.

HTTP Request
Method: GET
Endpoint: api/transactions/{order_id}
Headers
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token}
MID: {MID}
Body
-

HTTP Response
Parameter Type Description
time number Response time (in milliseconds)
status_ number HTTP Status Code
code
status_ string Status Message
message
result object Parameter Type Description Condition
Same json body as in Webhook Payment Notification
token string The same token to Only when the
initiate webpage payment status is
session (for checking PENDING
purpose)
redirect_url string Redirect URL with Only when the
query payment status is
PENDING

Payment Status
SUCCESS = 'Transaction success';
PENDING = 'Transaction is created after webpage is requested';
WAITING = 'Transaction waiting for payment confirmation';
FAILED = 'Transaction failed';
CANCELED = 'Transaction canceled’;

10
YUKK Payment Integration – API Documentation

Webhook_________________________________________________________
Webhook Payment Notification
The system will send a complete payment status notification of the requested payment from a
transaction.
Headers
Content-Type: application/json
Signature: openssl_digest(client_secret+order_id+pmt_channel_code+amount+status, ‘sha512’)
Body
Parameter Type Description Value
code string Yukk transaction code
order_id string Partner transaction code
grand_total integer Total amount to be paid
va object Parameter Type Description
account_id string The last 8 digit of VA
number (for Fixed type
only)
number string VA number (for both fixed
and dynamic type)
expired_at datetime Expiry time of VA number
(default value is 24hours
after request date)
expires_in Integer Sesi timeout dalam satuan
detik
customer_name string Customer full name
customer_phone string Customer phone number
customer_email string Customer email
request_at datetime Payment request time Format: YYYY-MM-DD
hh:mm:ss
paid_at datetime Payment paid time Format: YYYY-MM-DD
hh:mm:ss
notes string Other notes if necessary
status string Payment status that will SUCCESS / FAILED
be sent to notification url
merchant_branch object Parameter Type Description
name string Merchant name
payment_channel object Parameter Type Description
code Payment channel code
name Payment channel name
image_url URL logo (png/jpg/jpeg) of
payment channel
category object Para Type Description
meter
code string Payment
category
code
name string Payment
category
name

HTTP Response
When HTTP status_code given from partner is not 200 (webhook failed to be sent), our system
will automatically retry to hit the webhook five (5) times every interval of one (1) minute. If the
status is still not 200, partner can hit API Check Payment Status to get latest status.

11
YUKK Payment Integration – API Documentation

JSON Examples___________________________________________________
HTTP Response for Grouping == 0
{
"time": 790,
"status_code": 200,
"status_message": "Payment channels.",
"result": [
{
"code": "QRIS",
"name": "QRIS",
"description": null,
"image_url": null,
"category": {
"code": "QRIS",
"name": "QRIS"
}
},
{
"code": "OVO",
"name": "OVO",
"description": null,
"image_url": null,
"category": {
"code": "E_WALLET",
"name": "E-Wallet"
}
},
{
"code": "GOPAY",
"name": "GoPay",
"description": null,
"image_url": null,
"category": {
"code": "E_WALLET",
"name": "E-Wallet"
}
}
]
}

HTTP Response for Grouping == 1

{
"time": 1249,
"status_code": 200,
"status_message": "Payment channels.",
"result": [
{
"name": "QRIS",
"code": "QRIS",
"payment_channels": [
{
"code": "QRIS",
"name": "QRIS",
"image_url": null
}
]
},
{
"name": "E-Wallet",
"code": "E_WALLET",
"payment_channels": [
{
"code": "OVO",
"name": "OVO",
"image_url": null
},
{
"code": "GOPAY",
"name": "GoPay",
"image_url": null
}
]
}
]
}

12
YUKK Payment Integration – API Documentation

HTTP Request for Request Payment

{
"request_time": 1638794952,
"payment": {
"pmt_channel_code": "VA_PERMATA"
},
"va": {
"account_id": "12345678",
"expires_in": 600
},
"order_details": {
"order_id": "ORDER10004",
"amount": 15000,
"shipping_fee": 10000
},
"customer": {
"name": "Ata",
"phone": "08997537677",
"email": "[email protected]"
},
"billing": {
"name": "Ata",
"phone": "08997537677"
},
"session_timeout": 1800,
"notification_url": "http://localhost",
"callback_url": "http://localhost:8000"
}

Webhook for Webhook Payment Notification

{
"code": "PGW20211109442516181",
"order_id": "ORDER10004",
"grand_total": 15000,
"va ": {
"account_id": "12345678",
"number":"7788561212345678",
"expired_at":"2021-11-10 04:33:03",
"expires_in": 1800
}
"customer_name": "Ata",
"customer_phone": "08997537677",
"customer_email": "[email protected]",
"request_at": "2021-11-09 04:33:03",
"paid_at": "2021-11-09 04:33:03",
"notes": null,
"status": "SUCCESS",
"merchant_branch": {
"name": "Yukk Branch"
},
"payment_channel": {
"code": "VA_PERMATA",
"name": "Virtual Account PERMATA",
"image_url": null,
"category": {
"code": "BANK_TRANSFER",
"name": "Bank Transfer"
}
}
}

HTTP Response for API Check Payment Status (Status = “PENDING”)

{
"time": 218,
"status_code": 200,
"status_message": "Transaction.",
"result": {
"code": "PGW20220218989466609",
"order_id": "AO1645155590",
"grand_total": 1000,
"customer_name": "Alexander Kurnia S",
"customer_phone": "6281808466990",
"customer_email": "[email protected]",
"request_at": "2022-02-18 10:39:50",
"paid_at": null,

13
YUKK Payment Integration – API Documentation

"notes": null,
"status": "PENDING",
"token":
"YUKK:eyJpdiI6IndwemtQYjY1RlJxY2h0eGxadWJwaHc9PSIsInZhbHVlIjoiYUg5UlI4MTg1WkY
3YjhOSjZCT2R1UGROZzE1Rk42OVRkMXZpeE10TDRNdz0iLCJtYWMiOiI1ZTA0ZGZmODNlNDQ5YjVk
Y2RlOTZlMTY4MGM0NTczMzllNjYzMTFjYjE3OTA5ZGIyMDFhMDkyZTIzMTY1MWY4IiwidGFnIjoiI
n0=",
"redirect_url":
"https:\/\/fanyv88.com:443\/http\/localhost:3000?token=YUKK%3AeyJpdiI6IkFaeklkbFdGK2hseWVKcUp1UUZBcnc
9PSIsInZhbHVlIjoiREV3NDVUWllTSmJ5aVdIRmdlaHUvVTVSNUgwd2ZZMWprUnpXdG5aUVR4Yz0i
LCJtYWMiOiI1MzliZjJhZTBhYTNkODdhM2Y0YmU3NDBkYzc2MTM1ZjcwYjM3YTk4ZmYzNGU1M2ZjY
jZlNTkyNTVlZDFjOGJjIiwidGFnIjoiIn0%3D&callback_url=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Flocalhost%3A8
000",
"merchant_branch": {
"name": "Yukk Branch"
},
"payment_channel": {
"code": "CREDIT_CARD",
"name": "Credit Card",
"image_url": null,
"category": {
"code": "CREDIT_CARD",
"name": "Credit Card"
}
},
}
}

HTTP Response for Request VA (via API)

{
"time": 181,
"status_code": 200,
"status_message": "Successful.",
"result": {
"va": {
"number": "111111101347329097",
"expired_at": "2022-02-23 13:47:34"
}
}
}

14
YUKK Payment Integration – API Documentation

HTTP Response Code

HTTP Status Code Status Message
200 Success
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Invalid request body

Other Information
Testing Credentials
All Payment and VA Dynamic
Starting from v1.1.3, dummy account will NOT be provided anymore and each partner should
have their own testing account.
Ask our Account Manager team to get access of sandbox YUKKPG and staging dashboard.
The testing credentials are inside the staging dashboard.

YUKKPG Sandbox
Sandbox in YUKKPG is solely for testing purpose and is not directly connected with payment
services, therefore does not require real money in testing.
By default, every transaction with correct JSON format will return SUCCESS. If you want to try
FAILED transaction, put prefix “FD_” on your order_details.order_id when hitting API Request
Payment.

URL Domain Environment

Staging (Sandbox): dev.api.yukkpay.com
Production: api.yukkpay.com

Contact
Tim Business Integration
Alex - +62 818-0846-6990

Tim Technology
Gabriella - +62 878-0011-2965

15