PayPay Open Payment Api
API docs by Redocly

Points Code (1.0)

Introduction

PayPay Points Code API is designed to be used by our partners to perform Points Code related operations so as to deliver the best experience to end users. After being onboarded as a PayPay Client,you will have the following capabilities:

  • Create Points Code (charge code) for an end user instantly
  • Check your remaining Deposit Balance (budget)

This document will be focusing on APIs that support the above functionalities.
In addition, PayPay Gift Certificate Code is also supported. When using it, please read "Points Code" as "Gift Certificate Code".

Onboard merchant

To start utilizing our Open API platform, first the business needs to be onboarded as a PayPay merchant. This process usually consists of information collection, manual verification, contract confirmation and credentials issuance. After becoming a merchant on PayPay, the following items would be set up for the client:

  • API key and secret
  • Allowed authorization callback domains
  • Client IP whitelist This setup can be managed using our merchant panel or by getting in touch with a sales representative. For Points Code API, it also requires creation of Points Code groupId. Merchants are allowed to have multiple Points Code groupId based on the business requirement. The operation of creating Points Code groupId needs to be set up by your sales representative. Access by users to the PayPay app and PayPay web screen from outside Japan is restricted. Please contact us for details.

Specify merchant in request

Every time an API is called, the merchant identifier needs to be passed along with the request. There are two ways to pass the merchant identifier:

In a query string parameter:

?assumeMerchant={MerchantId}

Or in HTTP headers:

X-ASSUME-MERCHANT: {MerchantId}

If both are provided, the query string parameter would take precedence.

API Authentication

Everything related to OPA API Authorization is described here.

Error Handling

PayPay OPA uses HTTP response status codes and OPA error codes to indicate the success or failure of requests. With this information, you can decide what error handling strategy to use. In general, PayPay OPA returns the following HTTP response status codes.

Response code list

Common response code

Status Code Description
200 SUCCESS Success
400 INVALID_REQUEST_PARAMS The information provided by the request contains invalid data, e.g., unsupported currency.
400 MISSING_REQUEST_PARAMS The set parameter is invalid.
401 UNAUTHORIZED No valid api key and secret provided
401 OP_OUT_OF_SCOPE The operation is not permitted.
404 OPA_CLIENT_NOT_FOUND OPA Client not found
429 RATE_LIMIT Too many requests
500 SERVICE_ERROR A service error has occurred.
500 INTERNAL_SERVER_ERROR This code means that something went wrong, but we don't know exactly if the transaction has happened or not. It should be treated as unknown payment status.
503 MAINTENANCE_MODE Sorry, we are down for scheduled maintenance.

Create Points Code

Status Code Description
400 BUDGET_NOT_ENOUGH Points Code group doesn't have enough budget.
400 EXCEED_CHARGE_CODE_GROUP_MAX_PERIOD The period between startAt and endAt is over group maxPeriodDays setting
400 GIFT_CARD_GROUP_NOT_EXIST Points Code group does not exist.
400 INVALID_CHARGE_CODE_AMOUNT Points Code value is less then minimum limit amount.

API General Request ID

In principle, all API responses include an X-REQUEST-ID in the response header (with some exceptions). When contacting PayPay support, please provide this request ID.

Format: Alphanumeric characters and hyphens (maximum 64 characters)

Example:

OPA45F681001AEF4605B2A50939F611F4B8

Points Code APIs

Create Points Code

Create new Points Code. For timeout and internal error(5XX HTTP status codes) , merchants can safely retry the request with same requestId.

Timeout: 30s

Request Body schema: application/json
requestId
required
string

RequestId will be the idempotency key for creating Points Code

groupId
required
integer <int64>
giftCardName
required
string [ 1 .. 40 ]

Points Code name which will be displayed in PayPay app after user tops up

giftCardValue
required
integer <int32> [ 1 .. 999999 ]

Value of the Points Code in JPY

startAt
required
string <yyyy-MM-dd>
endAt
required
string <yyyy-MM-dd>

Responses

Request samples

Content type
application/json
{
  • "requestId": "ea233cbd-f949-42f3-98e7-ddd1cb5e6ffd",
  • "groupId": 29952775505428480,
  • "giftCardName": "Points Code 01",
  • "giftCardValue": 1000,
  • "startAt": "2021-10-10",
  • "endAt": "2022-10-09"
}

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}

Get group budget

Get all groups budget based on merchant.

Timeout: 15s

Responses

Response samples

Content type
application/json
{
  • "resultInfo": {
    },
  • "data": {
    }
}