Launched in 2018, PayPay has become Japan's leading mobile payment app, with over 65 million users. With widespread acceptance, PayPay has achieved a payment ratio exceeding 45%, surpassing other digital wallets in Japan. Learn more.

Payment Method Properties

Make an PayPay Payment

One-time PayPay payments follow our standardized REDIRECT payment flow. However, we recommend including all relevant settings for any authentication methods you support.

To create a PayPay payment, you'll need to provide the following data at minimum when calling our /v1/payment-charges API:

Request

POST /v1/payment-charges

{
  "paymentMethod": "PAYPAY",
  "paymentDescriptor": "Order Description",
  "amount": {
    "value": 10,
    "currency": "JPY"
  },
  "consumer": {
    "name": "John Smith",
    "country": "JP"
  },
  "authenticationSettings": [
    {
      "type": "REDIRECT",
      "settings": {
        "returnUrl": "https://www.your-return-page.com/"
      }
    }
  ]
}

Response

You'll receive one of our standard payment charge responses (see potential responses in the API Reference)

{
  "id": "charge_X0O78tadFHrZCbGhkycPk",
  "status": "AUTHENTICATION_PENDING",
  
  // ...
  
  "authenticationMethods": [
    {
      "type": "REDIRECT",
      "details": {
        "requestUrl": "https://redirection-target.com",
        "requestMethod": "GET"
      }
    }
  ]
}

Consumer Authentication

PayPay requires a consumer authentication step before the payment is authorized and captured.

In your response to your charge creation request, you will receive the authenticationMethods list with an authentication method of standard type REDIRECT

Redirect the consumer to the page url specified in the requestUrl field. The consumer will be taken to PayPay's pages to log in to their account and approve the payment.

The payment charge will remain in the AUTHENTICATION_PENDING state until the consumer confirms the payment in their app. After this, the charge will transition to the CAPTURED state.

Handling the Payment Result

The consumer will be redirected to the authenticationMethods.settings.returnUrl provided in the initial payment charge creation request, depending on whether the authorization is a success, a failure, or if the user cancelled/aborted the flow.

If the consumer fails to authenticate the payment within the timeout window, the charge will transition to the DISCARDED state.

You can receive webhooks for all changes to the payment charge state and use these to build business logic such as delivering the goods when the charge is CAPTURED.

Recurring Payments

PayPay offers recurring payment support - we simplify this flow for you with our Payment Agreements API.

Create the Payment Agreement

To set up a recurring agreement for PayPay, you'll need to provide at minimum the following data when calling our /v1/payment-agreements API:

You can also include the initialPaymentCharge object in this agreement creation call to immediately initiate the first payment without making a separate call. If you include this object, you'll need to specify:

• The exact amount.value and amount.currency of the first payment

Request

{
    "paymentMethod": "PAYPAY",
    "startDate": "2023-03-26T20:24:27Z",
    "consumer": {
        "name": "Jim Sim",
        "country": "JP"
    },
    "authenticationSettings": [
        {
            "type": "REDIRECT",
            "settings": {
                "returnUrl": "https://www.your-merchant-success-page.com/"
            }
        }
    ],
    "initialPaymentCharge": {
        "paymentDescriptor": "Order Description",
        "amount": {
            "value": 1000,
            "currency": "JPY",
            "merchantPaymentChargeReference": "YOURREFERENCEHERE"
        },
        "order": {
            "orderReferenceNumber": "42342342423423"
        }
    }
}

If you don't include an initialPaymentCharge during agreement creation, you'll need to make a separate API call to /v1/payment-agreements/{agreement_id}/payment-charges to create the first charge.

Response

You'll receive one of our standard payment agreement responses (see responses in the API Reference)

{
  "id": "agrmt_X0O78tadFHrZCbGhkycPk",
  "status": "AUTHENTICATION_PENDING",
  "startDate": "2023-03-26T20:24:27Z",
  "initialPaymentChargeId": "charge_X0O78tadFHrZCasfhkycPk",

  "authenticationMethods": [
    {
      "type": "REDIRECT",
      "details": {
        "requestUrl": "https://some-redirection-page.com",
        "requestMethod": "GET"
      }
    }
  ]
}

Redirect the consumer to url specified in requestUrl. The consumer will be taken to PayPay to log into their account and approve the payment agreement.

Once the consumer has confirmed the recurring agreement creation, the agreement status will transition to ACTIVE, and subsequent payments can be made without consumer interaction.

Make Subsequent Recurring Charges

Once you've set up a payment agreement, it's simple to create subsequent charges against it. In your /v1/payment-agreements/{agreement-id}/payment-charges/ request, you just need to include:

{  
    "amount": {  
        "amount": 9000,  
        "currency": "JPY"  
    }, 
    "paymentDescriptor": "Order Description",
    "order":{
         "orderReferenceNumber": "42342342423423"
    },
    "merchantPaymentChargeReference": "external-identifier", //optional  
		"autoCapture": true  
}

You will receive webhooks for all charges created under a Payment Agreement the same way you would for individual charges, and can respond accordingly.