PayPay Open APIs
Handling some Specific Scenarios

User Account Linking
Merchant
AppMerchant
BackendCreate JWT Token

PayPay Web

PayPayBackendCreate QR CodeQR Code URL
Open PayPay WebView
User Action

User Authorizes

Redirect URL with JWTWebhook for Authorization Result

Payment Flow
Merchant
AppMerchant
BackendPayPayBackendUser Confirms Order
Transaction/v1/payments

Payment Result

Check order Status
In case ofabove
sequence
timeout/v1/payments/{merchantPaymentId}

Payment Result

Refund Flow
Merchant
AppMerchant
BackendPayPayBackendUser Refunds OrderRefund/v1/refunds

Refund Result

Check order Status
In case ofabove
sequence
timeout/v1/refunds/{merchantRefundId}

Refund Result

Handling Duplicate Transactions
Merchant
What is a Duplicate Payment: When a merchantrequests 2 payments for the same user authorization id forthe same amount in 5 minutes we label the second
payment request as a duplicate payment request

PayPay/v1/payments
Order 1, 01:00:00 PM
User A, 10 JPY
Success

Default Handling for Duplicate Payment: When amerchant requests 2 payments for the same user
authorization id for the same amount in 5 minutes and theprevious payment is success, we fail the second payment
with the error code
SUSPECTED_DUPLICATE_PAYMENTWhat to Do: If a duplicate payment (same amount, sameuser authorization id) is genuinely needed within a periodof 5 minutes, please pass an additional parameter
agreeSimilarTransaction=true in the query parameters forcreate payment API/v1/payments
Order 2, 01:01:00 PM
User A, 10 JPY
Failure, SUSPECTED_DUPLICATE_PAYMENT/v1/payments?agreeSimilarTransaction=true
Order 2, 01:01:00 PM
User A, 10 JPYSuccessHandling Error Codes | Failure Scenarios
HTTP Response CodeError Code

What it Means

What to Do

400

INVALID_PARAMS

Transaction has failed

Please recheck the request parameters

400

UNACCEPTABLE_OP

Transaction has failed

Please contact the merchant help desk/ support team if thiscontinues

400

NO_SUFFICIENT_FUND

Transaction has failed

Please ask the user to topup PayPay and retry the payment

400

SUSPECTED_DUPLICATE_P
AYMENT

Transaction has failed

Described in detail in this slide. Click here

400

INVALID_USER_AUTHORIZATION_ID

Transaction has failedThe user authorization id has expired, Merchant needs tore-initiate the flow for acquiring user authorization id400

BAD_REQUESTTransaction has failed

Please recheck the request parameters

401

Transaction has failed

API Key/ Secret used for generating the authorization is incorrect404

Transaction has failed

The requested resource does not exist

429

Transaction has failed

Client has sent too many requests and is rate limited at our end,
Please retry after sometime

Transaction has failed

Transaction has been failed at PayPay Side, please try again
with a new merchantPaymentId500

TRANSACTION_FAILED

Handling Error Codes | Unknown Status Scenarios
MerchantHTTP
Response
CodeError Code

What it Means

PayPayWhat to Do

GET /v1/payments/{merchantPaymentId}

500502

INTERNAL_S
ERVER_ERRO
R

Payment Status
Undetermined

Payment Status
Undetermined

Option 1, Check Status(Recommended)
CREATED / COMPLETED / REFUNDED / FAILEDPOST /v1/payments
Response, FAILED
New merchantPaymentId needed
Success

503

Payment Status
Undetermined

DELETE /v1/payments/{merchantPaymentId}
Response, CREATED

504

Payment Status
UndeterminedAccepted

DELETE /v1/payments/{merchantPaymentId}

TIMEOUT

Payment Status
Undetermined

Option 2, Cancel
Payment
AcceptedFAQs: General
S.No.
1

Question

AnswerCan the same value be used for merchantPaymentId,
merchantRefundId, and merchantTopupId?

Yes the same can be used for merchantPaymentId,
merchantRefundId and merchantTopupId, however for consistency
and better understanding, we will recommend you to use different
values, following format is recommended:●●●2

What is the codeId? Do I need to know the valuesp_<> for paymentr_<> for refundt_<> for topup

CodeId is returned as a response, however the same is to be used incase of debugging only and value does not have any impact on theuser. In case you are receiving an error code repeatedly and need help
in debugging, we will request you to share the codeId with PayPay’s
tech team to help in quicker resolution.

FAQs: Create a Payment
S.No.

Question

Answer1

If I send the same merchantPaymentId will it return an errorcode?

The same response will be returned as sent during the first transaction

2

I am getting NO_SUFFICIENT_FUND even after adding
balance to my user account?

Please ensure you have changed the merchantPaymentId in therequest, if you pass the same merchantPaymentId we will give thesame response3

What does the response parameter status "CREATED" mean?

This can happen in the following cases:●

Case 1: If client sent the same "create payment" request twice
simultaneously, the later request may get the response with"CREATED" status, because the payment is under processing.
●
Case 2: might happen because of some unexpected issue, e.g.
db crashed, the state failed to update. that means the acquiring
order stuck at "CREATED" state. This case would be very rare,
and not worth to handle it in client logic. Should be covered byvarious recon job.
In case you are getting “CREATED” as a response, we will recommend
you to check for any possibility of simultaneous requests
4

What does the response parameter status "REFUNDED"
mean?

Refunded means that the transaction has been refunded in this case ,the data will also have details of the refundFAQs: Create a Payment
S.No.

Question

Answer5

What happens to handling of concurrent requests?

With the same merchant payment id we give the same response

6What is the response parameter metadata have included? Whatis the usage of metadata?

It is for the merchant to add anything they want to the metadata, we will
return the merchant whatever the merchant has put in to metadata7

Is it failed when I execute PaymentAPI for the suspend user?

Yes the transaction will be failed in case of suspended userFAQs: Get Payment Details
S.No.
1

Question

Answer

If I execute "get payment details API" after executing "Cancel apayment API", will 404 be returned?

Http response code 200 will be returned with status as failed

FAQs: Refund a Payment
S.No.

Question

Answer1

If I send the same merchantRefundId will it return an error code?

The same response will be returned as sent during the first transaction

2

What does the response parameter status "CREATED" mean?

Created means the request is accepted, however refunded will mean therefund has been processed3

Is the processing of RefundAPI in real time?

Realtime if merchant has adequate funds, else we have a retrialmechanism.

4I listened that RefundAPI can process only once. If I execute"Refund API" twice, will an error code be returned?

Yes that is correct, for multiple partial refund please refund the wholeamount and then capture the balance5

Is it success when I execute RefundAPI for the suspend user?

The transaction will be failed in case of suspended user

6

Can I cancel my REFUND?

No, once a refund is processed it cannot be cancelled

FAQs: Cancel a Payment
S.No.

Question

Answer

1

Does the transaction cease to exist on the PayPay side when I
execute Cancel a payment API?

The transaction exists in PayPay system, however the status of thesame is marked as Failed

2

Can I use the same transaction after executing Cancel apayment API?

No the same transaction id in the form of merchantPaymentId cannot be
used even after cancelling the payment

FAQs: Topup Wallet
S.No.

Question

Answer1

PaymentAPI has orderDescription. Isn't it necessaryorderDescription for TopUpAPI?

It is not necessary to pass orderDescription, however the same is highly
recommended as the same will be displayed in users Passbook

2

Is the processing of TopUpAPI in real time?

Yes processing of TopUp API is in realtime

3

If I send same merchantTopUpId that is it TopUpAPI will return
an error code?

The same response will be returned as sent during the first transaction

4

Is it failed when I execute TopUpAPI for the suspend user?

The transaction will be failed in case of suspended user