redirect-document

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.

API

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):

keyvalue
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

ParameterDescriptionUsage
titleTitle of the transactionrequired
typeType of the token that will be created[WEB_REDIRECT]
currencyCurrency for the transaction[JPY/USD/EUR/GBP]
nature-[ONE_OFF]
payerCustomer information object-
-nameCustomer namerequired
-phoneCustomer phonerequired
-emailCustomer emailrequired
-areaCodeCustomer phone area coderequired
-cityCustomer live cityrequired
-countryCustomer live countryrequired
successUrlURL to redirect on successful transactionrequired
failureUrlURL to redirect on failed transactionrequired
lineItemsArray of line items in the transaction-
-priceDataPricing information for the item-
—currencyCurrency of the item[JPY/USD/EUR/GBP]
—productDataProduct information for the item-
—-nameName of the productrequired
—unitAmountUnit amount of the itemrequired
—taxBehaviorTax behavior for the item[string]
-adjustableQuantityAdjustable quantity settings-
—enabledWhether adjustable quantity is enabled[true]
—minimumMinimum quantity allowedrequired
—maximumMaximum quantity allowedrequired
-quantityQuantity of the itemrequired

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

ParameterDescription
codeStatus code indicating the result of the request
messageA message describing the result of the request
dataObject containing transaction-related information
-createDtCreation date and time of the transaction
-payerPayer information
—namePayer’s name
—mobilePayer’s mobile number
—emailPayer’s email address
-totalTotal amount of the transaction
-subtotalSubtotal amount of the transaction
-checkoutTargetTarget information for checkout
—payerPayer information for checkout target
—-nameName of the payer for checkout target
—-phoneMobile number of the payer for checkout target
—-emailEmail address of the payer for checkout target
-titleTitle of the transaction
-currencyCurrency of the transaction
-typeType of transaction
-idTransaction ID
-statusStatus of the transaction
-checkoutUrlURL for the transaction checkout
-lineItemsArray of line items in the transaction
—idID of the line item
—priceDataPricing information for the line item
—-currencyCurrency of the line item
—-productDataProduct information for the line item
——nameName of the product for the line item
—-unitAmountUnit amount of the line item
—-taxBehaviorTax behavior for the line item
—adjustableQuantityAdjustable quantity settings for the line item
—-enabledWhether adjustable quantity is enabled
—-minimumMinimum quantity allowed for the line item
—-maximumMaximum quantity allowed for the line item
—quantityQuantity of the line item
—totalTotal amount of the line item
—subtotalSubtotal 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

ParameterDescription
codeStatus code indicating the result of the request
messageA message describing the result of the request
dataObject containing transaction-related information
-modeMode of the transaction
-payerPayer information object
—namePayer’s name
—emailPayer’s email address
-totalTotal amount of the transaction
-subtotalSubtotal amount of the transaction
-checkoutTargetTarget information for checkout
—payerPayer information for checkout target
—-nameName of the payer for checkout target
—-emailEmail address of the payer for checkout target
-titleTitle of the transaction
-currencyCurrency of the transaction
-typeType of transaction
-natureNature of the transaction
-idTransaction ID
-statusStatus of the transaction
-checkoutUrlURL for the transaction checkout
-lineItemsArray of line items in the transaction
—idID of the line item
—priceDataPricing information for the line item
—-currencyCurrency of the line item
—-productDataProduct information for the line item
——nameName of the product for the line item
—-unitAmountUnit amount of the line item
—-taxBehaviorTax behavior for the line item
—adjustableQuantityAdjustable quantity settings for the line item
—-enabledWhether adjustable quantity is enabled
—-minimumMinimum quantity allowed for the line item
—-maximumMaximum quantity allowed for the line item
—quantityQuantity of the line item
—totalTotal amount of the line item
—subtotalSubtotal amount of the line item
-createDtCreation date and time of the transaction
-fixedPspFixed Payment Service Provider
-tenantContextTenant context information
—nameName of the tenant context
-paymentsArray of payment information
—idPayment ID
—amountAmount of the payment
—currencyCurrency of the payment
—statusStatus of the payment
—modeMode of the payment
—createDtCreation date and time of the payment
—updateDtUpdate date and time of the payment

4. Error Code

CodeMessage
COS0001Incorrect Checkout Session.
COS0002Expired Checkout Session.
COS0003Payment Method not found.
COS0004Completed Checkout Session.
LIT0001Incorrect Line Item.
PYT0001Payment Record is not found.
PYT0002Payment Transaction Record is not found.
PYT0003Credit Card Number is not found.
PYT0004Incorrect Payment Service adapter/sdk.
PYT0005No pg feature is subscribed.
PYT0006This type of tenant is not allowed to perform this feature.
PMD0001Payment Method Record is not found.
SYS0000Success.
SYS9400API Client Error.
SYS9901SQL Error.
SYS9902Redis Key not existed / expired.
SYS9999Fail.
SYSA400AuthenticationException.
SYSA401AccessDeniedException.
PARM400Invalid field validation.
TENT400Tenant id / key not found.
TENT404TenantContext null in [PO] @PrePersist.