Copyright notation

The copyright of this document belongs to GRANDPAY. (hereinafter referred to as “GRANDPAY” or “Company”).
No part of this publication may be reproduced, modified, distributed, or similarly reproduced in any form or by any means, including electronic or mechanical, without the prior written permission of the Company.
All contents of this document are protected by the Japanese Copyright Law.
While every effort has been made to ensure the accuracy of the contents of this document, please contact us if you notice any omissions or other problems.

1. Introduction

This technical document explains how to successfully connect through a redirect link to the GRANDPAY payment gateway.

GRANDPAY Redirect API has production, sandbox environment, and so-called simulation mode that can be used for testing.

2. Preparation

Before the user connects to GRANDPAY Redirect API, please confirm that the user owns an API URL and Tenant key. This information can be found after login to the system in the API information section.

The API URL:

{{API_URL}}

The tenant key:

{{TENANT_KEY}}

3. API

This session will explain how to connect to the Redirect API provided by GRANDPAY.

Before the user creates a payment link for the customer to pay, it needs to call the 3.1 Get Authentication Token API to own the token first. After that, use the token to call the 3.2 Create Redirect Payment api create the payment.

3.1 Get Authentication Token

The API is for users to own the token for creating the payment with the 3.2 Create Redirect Payment API.

Request

Authorization:

Basic {{CLIENT_ID}}

Method: POST

https://{{API_URL}}/uaa/oauth2/token

Body raw (urlencoded):

key	value
grant_type	[custom-password-grant]
username	{{MERCHANT_PORTAL_LOGIN_ACCOUNT}}
credentials	{{MERCHANT_PORTAL_LOGIN_PASSWORD}}

Response

Body raw (json):

1. {
2. "code": "SYS0000",
3. "message": "Success.",
4. "data": {
5. "accessToken": "eyJraWQiOiJhbHRlY2gtdWFhIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI3MTQyMTU4NTI3MDQwMDYxNDQwIiwiYXVkIjoiY2xpZW50IiwibWV0YWRhdGEiOnsiaWRlbnRpZmllciI6IjY4MjE1Mjc0In0sIm5iZiI6MTcwMjkwNzQwNywic2NvcGUiOlsib3BlbmlkIl0sImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODA4MCIsImV4cCI6MTcwMjkxMTAwNywiaWF0IjoxNzAyOTA3NDA3fQ.Q2V-0VHv2ClMU4nIPwm7mDC9L-EasdJJ5XQ8VTpIx1ARM8gLmkVWg3VKbTlXbKphuBkY9sxcDyahsdLfiWcJQubBENEjfBZ9ET0epzGUvqYsnuXUCKQz6fEB-9rXlbuzMVm8ruH7DJ9_Vi6ThzFl-6WZtMacvy87qheMsVsVrrc2DGe2AtHKs_bnk32OV_blFxMy5BnGfGIi8Ns7pIpuHD4LYzA8eovdVHQXmVdbECpAjolAuaXgZMKx4MQNUgqIQ9rbtOzdGC5yaqHTBzu8nkaQIZE1mc7pptuJKWUaMdvkStzKdiK2uqqPsrlHSXqy45Y6wbhZ_6l7Pd5Pf5bgiQ",
6. "refreshToken": "9nQ2LjWZNH7iYoIDNshOtOAYlABIL6EFxqZfBNphqbPKZO7aAiV0X_gaHBq23TJ4Pe-mBy5FWFfB100l1g5fYxZ2XmNoObYvien0578lZ5NLjpUBjqPHlO7Ju6T1i5Yk",
7. "idToken": "eyJraWQiOiJhbHRlY2gtdWFhIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiI3MTQyMTU4NTI3MDQwMDYxNDQwIiwiYXVkIjoiY2xpZW50IiwibWV0YWRhdGEiOnsiaWRlbnRpZmllciI6IjY4MjE1Mjc0In0sImF6cCI6ImNsaWVudCIsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODA4MCIsImV4cCI6MTcwMjkxMTAwOSwiaWF0IjoxNzAyOTA3NDA5fQ.EKcUJUYLRuanMMtPicnsZ9DTT9irkW4pLruthoTWA6Da0ow8mWiQL2cy-a0yp9QF4WtFupMg3_b59N1PSfA8HcfyU-1QWxgZE-F42RgFzNUQsJS9SVOzjW3sbzTMKCQ3h2loxJCm60B4ClzHi-lX9DEA2k5KOgly0jD4IomjAcp1GvTHae1K6vWvqocwAah8bkJOfw1QaQchW_4J0GJCU2BEUYYrhAr-x8wn3SjG3U8Wr8UhDInq8_F6U-al3yP3z6V6l7s2zWBrhQcG5NkeEIHVkPlWZ050Aw5MU34xnbsksAHF5vBGnBcLSFk8om29jPRRyB33YsJSu86qXU4dgA",
8. "scopes": [
9. "openid"
10. ],
11. "tokenType": "Bearer",
12. "expiresIn": 3597
13. }
14. }

3.2 Create Redirect Payment

This API is for creating payments with the token owned in the 3.1 Get Authentication Token API.

Request

Authorization:

Bearer 3.1 Get Authentication Token.response.data.accessToken

Header: x-tenant-key

{{TENANT_KEY}}

Header: IsTestMode(Optional)

true

Method: POST

https://{{API_URL}}/p/v2/checkout-sessions

Body raw (json):

1. {
2. "title": "123",
3. "type": "WEB_REDIRECT",
4. "currency": "JPY",
5. "nature": "ONE_OFF",
6. "payer": {
7. "name": "Post Man",
8. "phone": "98765432",
9. "email": "postman@postman.com",
10. "areaCode": "081",
11. "city":"tokyo",
12. "country":"JP"
13. },
14. "successUrl": "https://merchant-api.com/callback?success=1",
15. "failureUrl": "https://merchant-api.com/callback?fail=1",
16. "lineItems": [
17. {
18. "priceData": {
19. "currency": "JPY",
20. "productData": {
21. "name": "Testing"
22. },
23. "unitAmount": "9999",
24. "taxBehavior": "string"
25. },
26. "adjustableQuantity": {
27. "enabled": true,
28. "minimum": 1,
29. "maximum": 10
30. },
31. "quantity": 1
32. }
33. ]
34. }

Request-Parameter Detail

Parameter	Description	Usage
title	Title of the transaction	required
type	Type of the token that will be created	[WEB_REDIRECT]
currency	Currency for the transaction	[JPY/USD/EUR/GBP]
nature	-	[ONE_OFF]
payer	Customer information object	-
-name	Customer name	required
-phone	Customer phone	required
-email	Customer email	required
-areaCode	Customer phone area code	required
-city	Customer live city	required
-country	Customer live country	required
successUrl	URL to redirect on successful transaction	required
failureUrl	URL to redirect on failed transaction	required
lineItems	Array of line items in the transaction	-
-priceData	Pricing information for the item	-
—currency	Currency of the item	[JPY/USD/EUR/GBP]
—productData	Product information for the item	-
—-name	Name of the product	required
—unitAmount	Unit amount of the item	required
—taxBehavior	Tax behavior for the item	[string]
-adjustableQuantity	Adjustable quantity settings	-
—enabled	Whether adjustable quantity is enabled	[true]
—minimum	Minimum quantity allowed	required
—maximum	Maximum quantity allowed	required
-quantity	Quantity of the item	required

Response

Body raw (json):

1. {
2. "code": "SYS0000",
3. "message": "Success.",
4. "data": {
5. "createDt": "2023-11-29 12:11:10",
6. "payer": {
7. "name": "Post Man",
8. "mobile": "68215274",
9. "email": "postman@olg-grandpay-backup.local"
10. },
11. "total": "9999",
12. "subtotal": "9999",
13. "checkoutTarget": {
14. "payer": {
15. "name": "Post Man",
16. "mobile": "68215274",
17. "email": "postman@olg-grandpay-backup.local"
18. }
19. },
20. "title": "123",
21. "currency": "JPY",
22. "type": "WEB_REDIRECT",
23. "id": "cos_ec16a750f73b412cd3dc411893e3406c",
24. "status": "OPEN",
25. "checkoutUrl": "https:/{{API_URL}}/checkout/ec16a750f73b412cd3dc411893e3406c",
26. "lineItems": [
27. {
28. "id": "12028722601660416",
29. "priceData": {
30. "currency": "JPY",
31. "productData": {
32. "name": "Testing"
33. },
34. "unitAmount": "9999",
35. "taxBehavior": "string"
36. },
37. "adjustableQuantity": {
38. "enabled": true,
39. "minimum": 1,
40. "maximum": 10
41. },
42. "quantity": 1,
43. "total": "9999",
44. "subtotal": "9999"
45. }
46. ]
47. }
48. }

Response-Parameter Detail

Parameter	Description
code	Status code indicating the result of the request
message	A message describing the result of the request
data	Object containing transaction-related information
-createDt	Creation date and time of the transaction
-payer	Payer information
—name	Payer’s name
—mobile	Payer’s mobile number
—email	Payer’s email address
-total	Total amount of the transaction
-subtotal	Subtotal amount of the transaction
-checkoutTarget	Target information for checkout
—payer	Payer information for checkout target
—-name	Name of the payer for checkout target
—-phone	Mobile number of the payer for checkout target
—-email	Email address of the payer for checkout target
-title	Title of the transaction
-currency	Currency of the transaction
-type	Type of transaction
-id	Transaction ID
-status	Status of the transaction
-checkoutUrl	URL for the transaction checkout
-lineItems	Array of line items in the transaction
—id	ID of the line item
—priceData	Pricing information for the line item
—-currency	Currency of the line item
—-productData	Product information for the line item
——name	Name of the product for the line item
—-unitAmount	Unit amount of the line item
—-taxBehavior	Tax behavior for the line item
—adjustableQuantity	Adjustable quantity settings for the line item
—-enabled	Whether adjustable quantity is enabled
—-minimum	Minimum quantity allowed for the line item
—-maximum	Maximum quantity allowed for the line item
—quantity	Quantity of the line item
—total	Total amount of the line item
—subtotal	Subtotal amount of the line item

3.3 Check Payment Status

This API is for checking the payment status in 3.2 Create Redirect Payment. All related transaction can finded in response.data.payments.

Request

Authorization:

Bearer 3.1 Get Authentication Token.response.data.accessToken

Header: x-tenant-key

{{TENANT_KEY}}

Header: IsTestMode(Optional)

true

Method: GET

https://{{API_URL}}/p/v2/checkout-sessions/{{`3.2 Create Redirect Payment.response.data.id`}}

Response

Body raw (json):

1. {
2. "code": "SYS0000",
3. "message": "Success.",
4. "data": {
5. "mode": "TEST",
6. "payer": {
7. "name": "Post Man",
8. "email": "postman@postman.com"
9. },
10. "total": "9999",
11. "subtotal": "9999",
12. "checkoutTarget": {
13. "payer": {
14. "name": "Post Man",
15. "email": "postman@postman.com"
16. }
17. },
18. "title": "Testing",
19. "currency": "JPY",
20. "type": "WEB_REDIRECT",
21. "nature": "ONE_OFF",
22. "id": "cos_test_f2ee56af02cabe547d8343ac27e232f1",
23. "status": "EXPIRED",
24. "checkoutUrl": "https://grand-pay.dev.pg.at-dev.io/checkout/test_f2ee56af02cabe547d8343ac27e232f1",
25. "lineItems": [
26. {
27. "id": "125854347663 056",
28. "priceData": {
29. "currency": "JPY",
30. "productData": {
31. "name": "Testing"
32. },
33. "unitAmount": "9999",
34. "taxBehavior": "string"
35. },
36. "adjustableQuantity": {
37. "enabled": true,
38. "minimum": 1,
39. "maximum": 10
40. },
41. "quantity": 1,
42. "total": "9999",
43. "subtotal": "9999"
44. }
45. ],
46. "createDt": "2024-01-17 08:00:47",
47. "p": "bvk",ˆ
48. "tenantContext": {
49. "name": "Merchant - Main Store"
50. },
51. "payments": [
52. {
53. "id": "p_7153295345353490432",
54. "amount": "9999",
55. "currency": "JPY",
56. "status": "COMPLETED",
57. "mode": "TEST",
58. "createDt": "2024-01-17 08:01:52",
59. "updateDt": "2024-01-17 08:01:52"
60. },
61. {
62. "id": "p_7153295177740713984",
63. "amount": "9999",
64. "currency": "JPY",
65. "status": "REJECTED",
66. "mode": "TEST",
67. "createDt": "2024-01-17 08:01:12",
68. "updateDt": "2024-01-17 08:01:12"
69. }
70. ]
71. }
72. }

Response-Parameter Detail

Parameter	Description
code	Status code indicating the result of the request
message	A message describing the result of the request
data	Object containing transaction-related information
-mode	Mode of the transaction
-payer	Payer information object
—name	Payer’s name
—email	Payer’s email address
-total	Total amount of the transaction
-subtotal	Subtotal amount of the transaction
-checkoutTarget	Target information for checkout
—payer	Payer information for checkout target
—-name	Name of the payer for checkout target
—-email	Email address of the payer for checkout target
-title	Title of the transaction
-currency	Currency of the transaction
-type	Type of transaction
-nature	Nature of the transaction
-id	Transaction ID
-status	Status of the transaction
-checkoutUrl	URL for the transaction checkout
-lineItems	Array of line items in the transaction
—id	ID of the line item
—priceData	Pricing information for the line item
—-currency	Currency of the line item
—-productData	Product information for the line item
——name	Name of the product for the line item
—-unitAmount	Unit amount of the line item
—-taxBehavior	Tax behavior for the line item
—adjustableQuantity	Adjustable quantity settings for the line item
—-enabled	Whether adjustable quantity is enabled
—-minimum	Minimum quantity allowed for the line item
—-maximum	Maximum quantity allowed for the line item
—quantity	Quantity of the line item
—total	Total amount of the line item
—subtotal	Subtotal amount of the line item
-createDt	Creation date and time of the transaction
-fixedPsp	Fixed Payment Service Provider
-tenantContext	Tenant context information
—name	Name of the tenant context
-payments	Array of payment information
—id	Payment ID
—amount	Amount of the payment
—currency	Currency of the payment
—status	Status of the payment
—mode	Mode of the payment
—createDt	Creation date and time of the payment
—updateDt	Update date and time of the payment

4. Error Code

Code	Message
COS0001	Incorrect Checkout Session.
COS0002	Expired Checkout Session.
COS0003	Payment Method not found.
COS0004	Completed Checkout Session.
LIT0001	Incorrect Line Item.
PYT0001	Payment Record is not found.
PYT0002	Payment Transaction Record is not found.
PYT0003	Credit Card Number is not found.
PYT0004	Incorrect Payment Service adapter/sdk.
PYT0005	No pg feature is subscribed.
PYT0006	This type of tenant is not allowed to perform this feature.
PMD0001	Payment Method Record is not found.
SYS0000	Success.
SYS9400	API Client Error.
SYS9901	SQL Error.
SYS9902	Redis Key not existed / expired.
SYS9999	Fail.
SYSA400	AuthenticationException.
SYSA401	AccessDeniedException.
PARM400	Invalid field validation.
TENT400	Tenant id / key not found.
TENT404	TenantContext null in [PO] @PrePersist.