Pay Credit

Headers

Field Name

Mandatory

Description

Content-Type

Yes

application/json

X-Verify

Yes

SHA256(base64 encoded payload + '/v3/merchant/credit/pay' + salt key) + '###' + salt index

{
  "userAuthToken": "USER_TOKEN568909123",
  "merchantId": "PPE_MRCH_123",
  "transactionId": "TRX_MRCH_123",
  "amount": 2500,
  "merchantOrderId": "MRC_ORD_123",
  "creditType": "CREDIT",
  "paymentInstrument": {
    "instrumentType": "ACCOUNT",
    "instrumentId": "instrumentUniqueId"
  },
  "message": "transaction remarks"
}
{ 
  "request" : "ewogICJ1c2VyQXV0aFRva2VuIjogIlVTRVJfVE9LRU41Njg5MDkxMjMiLAogICJtZXJjaGFudElkIjogIlBQRV9NUkNIXzEyMyIsCiAgInRyYW5zYWN0aW9uSWQiOiAiVFJYX01SQ0hfMTIzIiwKICAiYW1vdW50IjogMjUwMCwKICAibWVyY2hhbnRPcmRlcklkIjogIk1SQ19PUkRfMTIzIiwKICAiY3JlZGl0VHlwZSI6ICJDUkVESVQiLAogICJwYXltZW50SW5zdHJ1bWVudCI6IHsKICAgICJpbnN0cnVtZW50VHlwZSI6ICJBQ0NPVU5UIiwKICAgICJpbnN0cnVtZW50SWQiOiAiaW5zdHJ1bWVudFVuaXF1ZUlkIgogIH0sCiAgIm1lc3NhZ2UiOiAidHJhbnNhY3Rpb24gcmVtYXJrcyIKfQ=="
}
{
  "mobileNumber": "9988776655",
  "merchantId": "PPE_MRCH_123",
  "transactionId": "TRX_MRCH_123",
  "amount": 2500,
  "merchantOrderId": "MRC_ORD_123",
  "creditType": "CREDIT",
  "paymentInstrument": {
    "instrumentType": "VPA_TOKEN",
    "instrumentId": "instrumentUniqueId"
  },
  "message": "transaction remarks"
}
{ 
  "request" : "ewogICJtb2JpbGVOdW1iZXIiOiAiOTk4ODc3NjY1NSIsCiAgIm1lcmNoYW50SWQiOiAiUFBFX01SQ0hfMTIzIiwKICAidHJhbnNhY3Rpb25JZCI6ICJUUlhfTVJDSF8xMjMiLAogICJhbW91bnQiOiAyNTAwLAogICJtZXJjaGFudE9yZGVySWQiOiAiTVJDX09SRF8xMjMiLAogICJjcmVkaXRUeXBlIjogIkNSRURJVCIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgImluc3RydW1lbnRUeXBlIjogIlZQQV9UT0tFTiIsCiAgICAiaW5zdHJ1bWVudElkIjogImluc3RydW1lbnRVbmlxdWVJZCIKICB9LAogICJtZXNzYWdlIjogInRyYW5zYWN0aW9uIHJlbWFya3MiCn0="
}
{
  "mobileNumber": "9988776655",
  "merchantId": "PPE_MRCH_123",
  "transactionId": "TRX_MRCH_123",
  "amount": 2500,
  "merchantOrderId": "MRC_ORD_123",
  "creditType": "CREDIT",
  "paymentInstrument": {
    "instrumentType": "VPA",
    "instrumentId": "[email protected]"
  },
  "message": "transaction remarks"
}
{ 
  "request" : "ewogICJtb2JpbGVOdW1iZXIiOiAiOTk4ODc3NjY1NSIsCiAgIm1lcmNoYW50SWQiOiAiUFBFX01SQ0hfMTIzIiwKICAidHJhbnNhY3Rpb25JZCI6ICJUUlhfTVJDSF8xMjMiLAogICJhbW91bnQiOiAyNTAwLAogICJtZXJjaGFudE9yZGVySWQiOiAiTVJDX09SRF8xMjMiLAogICJjcmVkaXRUeXBlIjogIkNSRURJVCIsCiAgInBheW1lbnRJbnN0cnVtZW50IjogewogICAgImluc3RydW1lbnRUeXBlIjogIlZQQSIsCiAgICAiaW5zdHJ1bWVudElkIjogImNsZWFydnBhQHlibCIKICB9LAogICJtZXNzYWdlIjogInRyYW5zYWN0aW9uIHJlbWFya3MiCn0="
}

Request Parameters

Field Name

Data Type

Mandatory

Description

userAuthToken

String

Conditional

userAuthToken generated from user linking. Not mandatory if mobile number is passed

mobileNumber

String

Conditional

Token to identify the user generated during otp verify call. Not mandatory if userAuthToken is passed.

merchantId

String

Yes

Unique Id assigned to the merchant in the PhonePe system. Assigned during merchant onboarding

transactionId

String

Yes

Unique Id generated by merchant for this transaction

amount

Long

Yes

Amount to be credited to the user. (in paise). Min: 1, Max: 1,00,000.00

merchantOrderId

String

No

Order Id for this transaction at merchant’s end (if any)

creditType

Enum

Yes

Identifier for type of credit. Possible Values = REFUND, CREDIT.

paymentInstrument

Object

Yes

Object containing details of destination instrument

message

String

No

Message to identify what the credit was for

subMerchantId

String

No

Tag to categorize merchant transactions.

Request Data Description: paymentInstrument fields

Field Name

Data Type

Mandatory

Description

instrumentType

String

Yes

Type of payment instrument payment. Possible values = VPA_TOKEN, VPA, ACCOUNT.

instrumentId

String

Yes

Unique identifier with instrumentType as VPA_TOKEN or ACCOUNT from /credit/options response .
VPA with instrumentType as VPA when not fetched from /credit/options call.

{
  "success": true,
  "code": "PAYMENT_PENDING",
  "message": "Your request is in pending state.",
  "data": {
    "merchantId": "PPE_MRCH_123",
    "transactionId": "TRX_MRCH_123",
    "providerReferenceId": "TTX_123_45",
    "amount": 2500,
    "paymentState": "PENDING",
    "payResponseCode": "CREATED"
  }
}

Response Parameters

Field Name

Data Type

Description

success

Boolean

Redundant field. To be ignored by merchants.

code

String

See "PAY CREDIT : Response Codes" table for a list of possible values and their meanings

message

String

Short message describing the code

data

Object

Object containing details of actual response data

Response Data Description: data level fields

Field Name

Data Type

Description

merchantId

String

Unique Id assigned to the merchant in PhonePe system. Assigned during merchant onboarding

merchantTransactionId

String

Unique Id generated by merchant for this transaction

providerReferenceId

String

PhonePe transactionId generated for the credit request

payResponseCode

String

PhonePe payment status code. Please note, this is a string and new values can be added as and when needed. Don’t use this field for making decisions

paymentState

String

PhonePe internal payment state. This is an informative field. Don’t use this field for making decisions, since new values can be added to it

PAY CREDIT : Response Codes

Code Value

Description

BAD_REQUEST

Invalid request payload

INTERNAL_SERVER_ERROR

Some went wrong at the server side. Merchant needs to call the transaction status API to verify transaction status

INVALID_TRANSACTION_ID

The transaction Id provided by the merchant is duplicated

INVALID_USER_AUTH_TOKEN

The user auth token provided for this token is either expired or not mapped to the merchant. Please regenerate the token & try again.

USER_NOT_FOUND

No user found for the given mobile number or userAuthToken.

INSTRUMENT_NOT_FOUND

The instrument Id entered is invalid. Make another call to /credit/options, select a valid instrumentId & try again.

ACCOUNT_NOT_FOUND

Invalid instrument Id. Handling should be the same as INSTRUMENT_NOT_FOUND.

VPA_NOT_FOUND

Invalid instrument Id. Handling should be the same as INSTRUMENT_NOT_FOUND.

BLOCKED_FRAUD

Business rule violation. Either the total amount to be credited exceeds the maximum amount allowed for a merchant OR to a user on a given day OR the maximum amount allowed for a given transaction.

PAYMENT_SUCCESS

Amount has been successfully credited to the user

PAYMENT_ERROR

Payment has failed

PAYMENT_PENDING

Payment is submitted for crediting the amount. Merchant needs to verify payment status by calling the transaction status API

Language
Click Try It! to start a request and see the response here!