get https://api.juspay.in/payout/merchant/v1/orders/?expand=fulfillment,payment,refund
Get order status is an API call to fetch the latest status for a particular payout request placed, based on the Query parameter: expand = fulfillment, payment or refund
NOTE:
The response shown for this API only shows the result for
expand = fulfillment. Possible (tentative) response parameters for expand = payment or expand = refund are shown in tables below.The response for this API (with expand = fulfillment) returns an updated fulfillments array with Transactions and Beneficiary details.
(click to open table)
expand = fulfillment) returns an updated fulfillments array with Transactions and Beneficiary details.(click to open table)
| Parameter | Type | Description |
|---|---|---|
| orderId | String | Unique Reference for the order. This will be the ID for any subsequent communications. |
| amount | String | Total order amount, which is the sum of all the fulfilment amounts |
| customerIdwwwwwwwwwww | String | Unique ID for the customer generated by the merchant. |
| createdAt | String | Date/time (ISO representation) when order was created |
| updatedAt: | String | Date/time (ISO representation) of the most recent update |
| type | String | "FULFILL_ONLY". |
| status | String | "FULFILLMENTS_SUCCESSFUL" unless otherwise indicated:Status codes and meaningCREATED Pending READY_FOR_FULFILLMENT Pending FULFILLMENTS_SCHEDULED Pending FULFILLMENTS_FAILURE Failure FULFILLMENTS_SUCCESSFUL Success FULFILLMENTS_MANUAL_REVIEW Check with bank |
| fulfillments: [[{...},{...},...] | Array of Objects | Status of fulfillment related items with details of transactions and Account/Card/Wallet/VPA details of each beneficiary. |
Parameters for each
fulfillments object in array: | Parameter | Type | Description |
|---|---|---|
| updatedBy:wwwwwwwwww | String | "DEFAULT" unless otherwise indicated |
| updatedAt | String | Date/time (ISO representation) of the fulfillment update |
| type | String | "ORDER" |
| id | String | Unique ID generated by Juspay for the fulfillment order. |
| createdAt | String | Date/time (ISO representation) when fulfillment order was created |
| status | String | "SUCCESS" unless otherwise indicated:Status codes and meaningSUCCESS This means that the fulfillment has been successfully executed. PENDING This would mean that the fulfillment has been queued with JusPay or with the downstream system. FAILURE We were unable to process the fulfillment successfully. You have to try again with a new unique_request_id.MANUAL_REVIEW This would mean that the fulfillment request was sent an ambigious response from the payment gateway and the merchant has to manually reconcile it with the payment gateway to get the proper response. Also, any fulfillment which are in pending for more than 10 days are sent for manual review. |
| statusUpdatedAt | String | Date/time (ISO representation) of fulfillment status update |
| merchantCustomerId | String | Unique ID generated by Juspay for the merchant. |
| preferredMethodList:wwt [string1, string2,..] | Array of Strings | This will define the list of methods to be used for fulfillments for instance - [“YESBANK_IMPS”,”CASHFREE_IMPS”] |
| fulfillmentMethodList: [string1, string2,..] | Array of Strings | The actual methods that were used for the fulfillment |
| amount | String | Amount to be processed for the particular fulfillment, which is the sum of all transaction amounts for the fulfillment. Sum of all the fulfilment amounts should be equal to the total order amount. |
| transactions: [[{...},{...},...] | Array of objects | Array containing details of each transaction in the fulfillment order |
Parameters for each transactions object in array:
| updatedAt | String | Date/time (ISO representation) of transaction update |
| transactionRef | String | Unique ID assigned to the transaction request (same as requestId in txnResponse object below). |
| timeStamp | String | Date/time (ISO representation) of transaction |
| status | String | "SUCCESS" unless otherwise indicated:Status codes and meaningSUCCESS This means that the transactions have been successfully executed. PENDING This would mean that a transaction has been queued with JusPay or with the downstream system. FAILURE We were unable to process the transaction successfully. You have to try again with a new unique_request_id.MANUAL_REVIEW This would mean that the transaction request was sent an ambigious response from the payment gateway and the merchant has to manually reconcile it with the payment gateway to get the proper response. Also, any transactions which are in pending for more than 10 days are sent for manual review. |
| gatewayRefId | String | Reference ID for the gateway used |
| fulfillmentMethod | String | The actual method that was used for transaction fulfillment - for instance: “YESBANK_IMPS” or ”CASHFREE_IMPS”. |
| createdAt | String | Date/time (ISO representation) when transaction order was created |
| amount | double | Amount to be processed for the particular transaction. Sum of all the fulfillment's transaction amounts should be equal to the total amount for the fulfillment. |
| txnResponse:wwwwwww {param1, param2,..} | JSON object | This object will contain a summary and status of the transaction |
Parameters for each
txnResponse object: | status | String | "SUCCESS" unless otherwise indicated (see table above). |
| requestId | String | Unique ID assigned to the transaction request (same as transactionRef in transactions object). |
| amount | Double | Amount to be processed for the particular transaction. Sum of all the fulfillment's transaction amounts should be equal to the total amount for the fulfillment. |
| beneficiaryDetails:wwwnw {param, object} | JSON object | These objects contain Account/Card/Wallet/VPA details of each beneficiary in which the payout is to be processed. |
Parameters for each beneficiaryDetails object:
| type | String | CARD for card transfer, UPI_ID for transfer to vpa, ACCOUNT_IFSC for transfer to account, and WALLET for transfer to Paytm Wallet |
| details:wwwwwwwwwwn {param1, param2,..} | JSON object | This object will contain the Account/Card/Wallet/VPA details |
Parameters for each
details object: | name | String | Name of beneficiary |
| account | String | Account of beneficiary (Required for transfer to account) |
| ifsc | String | IFSC of beneficiary (Required for transfer to account) |
| cardReference | String | CardReference to the card details stored in Juspay Card Vault(Required for card transfer) |
| bankCode | String | IIN of the card issuer - a list of bankCode & bankNames is provided (Required for card transfer) |
| brand | String | Card brand - “VISA/MASTERCARD/AMEX…” (Required for card transfer) Wallet brand - "PAYTM" (Required for wallet transfer) |
| cardType | String | “CREDIT” / "DEBIT" (Required for card transfer) |
| vpa | String | UPI id of beneficiary (Required for transfer to vpa) |
| walletIdentifier | String | Number with which user has registered Paytm Wallet. |
A possible response for expand = payment (click to view)
| Field | Type | Description |
|---|---|---|
| orderId | String | Unique Reference for the order. This will be the ID for any subsequent communications. |
| amount | String | Total order amount, which is the sum of all the payment amounts |
| customerIdwwwwwwwwi | String | Unique ID for the customer generated by the merchant. |
| createdAt | String | Date/time (ISO representation) when order was created |
| updatedAt: | String | Date/time (ISO representation) of the most recent update |
| type | String | "PAYMENTS_ONLY". |
| status | String | "PAYMENTS_SUCCESSFUL" unless otherwise indicated:Status codes and meaning CREATED Pending READY_FOR_PAYMENTS Pending PAYMENTS_SCHEDULED Pending PAYMENTS_FAILURE Failure PAYMENTS_SUCCESSFUL Success PAYMENTS_MANUAL_REVIEW Check with bank |
| payments: [{...},{....}...] | Array of objects | This array contains a series of payment instrument details (Parameters in object are listed in table below - click to open) |
Parameters for each payments object in array:
| Field | Type | Description |
|---|---|---|
| payment_method_type | String | Payment method type used when creating the mandate. Must be either CARD, NB, WALLET, or UPI. |
| payment_method | String | Payment method used when creating the mandate. Found in the given tables for the corresponding Payment API and transaction type. |
| updatedBy:wwwwwwwwww | String | "DEFAULT" unless otherwise indicated |
| updatedAt | String | Date/time (ISO representation) of the payment update |
| type | String | "PAYMENT" |
| id | String | Unique ID generated by Juspay for the payment order. |
| createdAt | String | Date/time (ISO representation) when payment order was created |
| status | String | "SUCCESS" unless otherwise indicated:Status codes and meaningSUCCESS This means that the payment has been successfully executed. PENDING This would mean that a payment has been queued with JusPay or with the downstream system. FAILURE We were unable to process the payment successfully. You have to try again with a new unique_request_id.MANUAL_REVIEW This would mean that the payment request was sent an ambigious response from the payment gateway and the merchant has to manually reconcile it with the payment gateway to get the proper response. Also, any payments which are in pending for more than 10 days are sent for manual review. |
| statusUpdatedAt | String | Date/time (ISO representation) of payment status update |
| merchantCustomerId | String | Unique ID generated by Juspay for the merchant. |
| amount | String | Amount to be processed for the particular payment. Sum of all the payment amounts should be equal to the total payment amount. |
| auth-type | String | Type of authentication used. |
| upi_details:wwwwwwnwww {payer_vpa} | Object String | UPI details related to customer. Payer VPA used during order creation. |
UPI Details Object Parameter:
| Field | Type | Description |
|---|---|---|
| payer_vpa | String | Payer VPA used during order creation. |
| wallet_details: {brand, walletIdentifier} | Object String | Wallet details of customer.wwnww |
Wallet Details Object Parameter:
| Field | Type | Description |
|---|---|---|
| brand | String | "PAYTM" (Required for wallet transfer) |
| walletIdentifier | String | Number with which user has registered Paytm Wallet. |
| card details: {param1, param2,...} | Object String | Card details.wwwwtwwwwww |
Card Details Object Parameters:
| Field | Type | Description |
|---|---|---|
| using_saved_card | Boolean | True if using a saved card |
| saved_to_locker | Boolean | True if card has been saved to locker |
| last_four_digits | String | Last four digits of card number |
| name_on_card | String | Card holder name. Should contain alphabetical characters only. |
| expiry_year | String | Expiry year of the card (Format: "yyyy") |
| expiry_month | String | Expiry month of the card (Format: "mm") |
| card_type | String | "CREDIT" or "DEBIT" |
| card_issuer | String | Code for bank that issued the card (Example: "HDFC Bank") |
| card_isin | String | International Securities Identification Number for card (Example: "545721") |
| card_brand | String | Brand of card ("MASTERCARD", "VISA", etc.) |
| bank_details: {param1, param2,...} | Object String | Bank detailswwwwwnwwwwwn |
Bank Details Object Parameters:
| Field | Type | Description |
|---|---|---|
| object | String | "bank_account" |
| id | String | Bank account ID generated by Juspay |
| customer_id | String | Customer ID sent in request. (Customer ID is provided by juspay or is the object reference ID given by merchant during customer creation.) |
| date_created | String | Date that account was created |
| bank_name | String | **Name of bank |
| account_number | String | Bank account number |
| beneficiary_name | String | Name of the customer in a given bank account |
| ifsc | String | IFSC code for a bank branch |
| validation_amount | String | Amount that account is validated for |
| currency | String | Type of currency |
| validation_status | String | Status of account (CREATED, PENDING, or ACTIVE) |
| last_validated | String | Time/date of most recent validation |
| metadata: {param1, param2, ....} | String | Custom key-value sets sent in previous request |
NOTE:
Only those parameters in bold may be necessary for the Bank Details Object.
A possible response for expand = refund (click to view)
| Field | Type | Description |
|---|---|---|
| orderId | String | Unique Reference for the order. This will be the ID for any subsequent communications. |
| amount | String | Total refund amount, which is the sum of all the individual refund amounts |
| customerIdwwwwwww | String | Unique ID for the customer generated by the merchant. |
| createdAt | String | Date/time (ISO representation) when order was created |
| updatedAt: | String | Date/time (ISO representation) of the most recent update |
| type | String | "REFUNDS_ONLY". |
| status | String | "REFUNDS_SUCCESSFUL" unless otherwise indicated:Status codes and meaning CREATED Pending READY_FOR_REFUNDS Pending REFUNDS_SCHEDULED Pending REFUNDS_FAILURE Failure REFUNDS_SUCCESSFUL Success REFUNDS_MANUAL_REVIEW Check with bank |
| Refunds: [{...},{...},..] | Array wwwwt | An array of Refund Objects with details of each refund. |
Refunds Object Parameters:
| Field | Type | Description |
|---|---|---|
| unique_request_id | String | Unique ID generated for the request |
| ref | String | Reference number provided by the bank for the refund |
| id | String | Unique ID generated by Juspay for the refund order. |
| type | String | "REFUND" |
| amount | String | Total amount to be processed for the particular refund. Sum of all the refund amounts should be equal to the total refund amount. |
| updatedBy:wwwwwwwwww | String | "DEFAULT" unless otherwise indicated |
| createdAt | String | Date time (ISO representation) when refund was created |
| updatedAt | String | Date/time (ISO representation) of the refund update |
| statusUpdatedAt | String | Date/time (ISO representation) of refund status update |
| status | String | "SUCCESS" unless otherwise indicated:Status codes and meaningSUCCESS This means that the refund has been successfully executed. PENDING This would mean that the refund has been queued with JusPay or with the downstream system. FAILURE We were unable to process the refund successfully. You have to try again with a new unique_request_id.MANUAL_REVIEW This would mean that the refund request was sent an ambigious response from the payment gateway and the merchant has to manually reconcile it with the payment gateway to get the proper response. Also, any refunds which are in pending for more than 10 days are sent for manual review. |
| merchantCustomerId | String | Unique ID generated by Juspay for the merchant. |
| error_message | String | Message if error occured |
| sent_to_gateway | Boolean | Set to 'true' if request was sent to gateway |
⭣
The request for the Order Status API consists of one Path parameter: orderId, one optional Query parameter: expand, and two Headers.