Nodepay API Specification

(paymenting APIs)

Version Date Author Description

1.0 05-Oct-2023 Vikram Initial draft

1.0 05-Oct-2023 Vikram Added API for

payment creation
Nodepay is a RSF certified payment solution from Plotch.ai for payments in the
ONDC network. These set of APIs can be used by third party apps to create,
delete, update and get status of payments which are being managed in Nodepay

Service endpoint: https://nodepay-api.plotch.ai/

APIs
1. payment/create
This api will create a payment in nodepay

Request
Method URL

POST payment/create/

Type Params Values

HEAD auth_token JWT

nodesso_id string

BODY {
"nodepay_account_user_id": "string",
"nodepay_payment_instance_id": "string",
"payment_id": "6527c56454105e766fc1477c",
"payment_created_time": "15:10:2023 22:20:50",
"invoice_number": "15/2023-24",
"payment_payer_info": {
"name": "Craftsvilla",
"phone": "9879879870",
"email": "[email protected]"
},
"payment_payee_info": {
"name": "Ideamasters",
"phone": "9879879870",
 "email": "[email protected]",
"address": "",
},
"receiver_app_id": "",
"receiver_app_uri": "",
"payment_mode": "bank/upi",
"payment_payee_bank": {
"beneficary_name": "string",
"bank_name": "string",
"bank_account_num": "string",
"bank_ifsc_code": "string",
"bank_branch_name": "string",
"bank_account_type": "current/savings"
},
"payment_payee_upi": {
"upi_vpa": "m787879@okhdfcbank",
"upi_phone": "9920199201"
},
"payment_details": {
"payment_amount": "90.00",
"payment_tcs_withheld": "1.00",
"payment_tds_withheld": "2.00",
"payment_remarks": "payment for ONDC order"
},
"payment_order_details": {
"payment_order_id":
"4597f703-e84f-431e-a96a-d147cfa142f9",
"payment_order_created_date": "DD:MM:YYYY
HH:MM:SS",
"payment_order_status": "processing",
"payment_order_provider_id": "67121",
"payment_order_value": "100",
"payment_order_commission_fee": "7.00",
"payment_order_packaging_charge": "7.00",
"payment_order_shipping_charge": "7.00",
"payment_order_convenience_charge": "7.00",
"payment_order_items": [
{
"payment_item_id": "18275-ONDC-1-9",
"payment_item_quantity": "1",
"payment_item_fulfillment_id": "100231",
"payment_item_fulfillment_status": "delivered",
 "payment_item_return_window": "P2D",
"payment_item_url":
"https://www.sd.com/prd/12121"
}
]
}
}

auth_token
auth_token must be sent with all client requests. The auth_token is a JWT token which helps
the server to validate the request source.

payment_id (string, mandatory)

payment_id is a client generated payment id which identifies the payment being created

payment_created_time (string, mandatory)

payment_created_time (DD:MM:YYYY HH:MM:SS) is the time and day when payment was
created by payment issuer on client side

payment_issuer_info (object, mandatory)

payment_issuer_info includes details of the customer/seller/client who has created the
payment. Name of the issuer is mandatory.

Response
Status Response

200 {
"api_action_status": “success”,
"noderetail_payment_id": “12133111”
}

auth_token (string) - all API calls must have this key in header
 403 {"error":"Auth token is missing."}

401 {"error":"Invalid auth token."}

500 {"error":"Something went wrong. Please try again later."}

2. payment/create_using_onconfirm
This api will create a payment in nodepay using on_confirm payload

Request
Method URL

POST payment/create_using_onconfirm/

Type Params Values

HEAD auth_token JWT

nodesso_id string

BODY {
"nodepay_account_user_id": "string",
"nodepay_payment_instance_id": "string",
"payment_id": "6527c56454105e766fc1477c",
"payment_created_time": "15:10:2023 22:20:50",
“on_confirm_payload”: {
“message”: {},
“context”:{}
}
}

auth_token
auth_token must be sent with all client requests. The auth_token is a JWT token which helps
the server to validate the request source.

payment_id (string, mandatory)

payment_id is a client generated payment id which identifies the payment being created

payment_created_time (string, mandatory)

payment_created_time (DD:MM:YYYY HH:MM:SS) is the time and day when payment was
created by payment issuer on client side

payment_issuer_info (object, mandatory)

payment_issuer_info includes details of the customer/seller/client who has created the
payment. Name of the issuer is mandatory.

Response
Status Response

200 {
"api_action_status": “success”,
"noderetail_payment_id": “12133111”
}

auth_token (string) - all API calls must have this key in header

403 {"error":"Auth token is missing."}

401 {"error":"Invalid auth token."}

500 {"error":"Something went wrong. Please try again later."}

3. payment/approve
This api will approve the payment created in nodepay

Request
Method URL
 POST payment/approve

Type Params Values

HEAD auth_token JWT

nodesso_id string

BODY {
"payment_id": "6527c56454105e766fc1477c",
"nodepay_account_user_id":"string",
"nodepay_payment_instance_id":"string",
"nodepay_payment_id": "121222"
"payment_auth_info": {
“auth_level”: “L1/L2”,
"authorizer_name": "Manoj",
"authorizer_phone": "9879879870",
"authorizer_email": "[email protected]"
}
}

auth_token
auth_token must be sent with all client requests. The auth_token is a JWT token which helps
the server to validate the request source.

payment_id (string, mandatory)

payment_id is a client generated payment id which identifies the payment being created

payment_created_time (string, mandatory)

payment_created_time (DD:MM:YYYY HH:MM:SS) is the time and day when payment was
created by payment issuer on client side

payment_issuer_info (object, mandatory)

payment_issuer_info includes details of the customer/seller/client who has created the
payment. Name of the issuer is mandatory.
Response
Status Response

200 {
"api_action_status": “success”,
"auth_status": “success”,
“auth_level”: “L1/L2”
}

auth_token (string) - all API calls must have this key in header

403 {"error":"Auth token is missing."}

401 {"error":"Invalid auth token."}

500 {"error":"Something went wrong. Please try again later."}

4. payment/status
This api will get details of a payment in nodepay including status & notes.

Request
Method URL

POST payment/status/

Type Params Values

HEAD auth_token JWT

nodesso_id string

BODY {
"payment_id": "6527c56454105e766fc1477c",
"nodepay_account_user_id":"string",
"nodepay_payment_instance_id":"string",
 "nodepay_payment_id": "121222",
"payment_network_order_id": "67676vcv-55758"
}

Response
Status Response

200 {
"api_action_status": “success”,
“nodepay_payment_id”:”121222”,

“nodepay_payment_status”:”paid/unpaid/payment_in_process/deleted”
,
“nodepay_payment_status_note”:”paid via bank”,
"nodepay_payment_details": {
"payment_paid_amount": "90.00",
"payment_paid_date": "DD:MM:YYYY HH:MM:SS",
“nodepay_payment_method”: “bank/upi”,
“nodepay_payment_utr”:”7876612213311”,
"nodepay_payment_remarks": “payment for ONDC order"
}
}

auth_token (string) - all API calls must have this key in header

403 {"error":"Auth token is missing."}

401 {"error":"Invalid auth token."}

500 {"error":"Something went wrong. Please try again later."}

5. payment/delete
This api will create a payment in nodepay

Request
 Method URL

POST payment/delete/

Type Params Values

HEAD auth_token JWT

nodesso_id string

BODY {
"nodepay_account_user_id":"string",
"nodepay_payment_instance_id":"string",
"payment_id": "6527c56454105e766fc1477c",
“nodepay_payment_id”:”121222”,
“payment_delete_note”: “payment value has
errors”,
}

auth_token
auth_token must be sent with all client requests. The auth_token is a JWT token which helps
the server to validate the request source.

payment_id (string)
payment_id is a client generated payment id which identifies the payment being created

payment_created_time (string)
payment_created_time (DD:MM:YYYY HH:MM:SS) is the time and day when payment was
created by payment issuer on client side

Response
Status Response

200 {
"api_action_status": “success”,
“nodepay_payment_id”:”121222”,
 “payment_id”:”787777”,
“nodepay_payment_delete_status”:”success/fail”
}

auth_token (string) - all API calls must have this key in header

403 {"error":"Auth token is missing."}

401 {"error":"Invalid auth token."}

500 {"error":"Something went wrong. Please try again later."}

6. payment/request
This api will create a payment in nodepay

Request
Method URL

POST payment/request/

Type Params Values

HEAD auth_token JWT

nodesso_id string

BODY {
"nodepay_account_user_id": "string",
"nodepay_payment_instance_id": "string",
"payment_id": "6527c56454105e766fc1477c",
"payment_request_time": "15:10:2023 22:20:50",
"invoice_number": "15/2023-24",
"payment_payer_info": {
"name": "Craftsvilla",
"phone": "9879879870",
"email": "[email protected]"
 },
"payment_payee_info": {
"name": "Ideamasters",
"phone": "9879879870",
"email": "[email protected]",
"address": "",
},
"receiver_app_id": "",
"receiver_app_uri": "",
"payment_mode": "bank/upi",
"payment_payee_bank": {
"beneficary_name": "string",
"bank_name": "string",
"bank_account_num": "string",
"bank_ifsc_code": "string",
"bank_branch_name": "string",
"bank_account_type": "current/savings"
},
"payment_payee_upi": {
"upi_vpa": "m787879@okhdfcbank",
"upi_phone": "9920199201"
},
"payment_details": {
"payment_requested_amount": "90.00",
"payment_tcs_withheld_expected": "1.00",
"payment_tds_withheld_expected": "2.00",
"payment_remarks": "payment for ONDC order"
},
"payment_order_details": {
"payment_order_id":
"4597f703-e84f-431e-a96a-d147cfa142f9",
"payment_order_created_date": "DD:MM:YYYY
HH:MM:SS",
"payment_order_status": "processing",
"payment_order_provider_id": "67121",
"payment_order_value": "100",
"payment_order_commission_fee": "7.00",
"payment_order_packaging_charge": "7.00",
"payment_order_shipping_charge": "7.00",
"payment_order_convenience_charge": "7.00",
"payment_order_items": [
{
 "payment_item_id": "18275-ONDC-1-9",
"payment_item_quantity": "1",
"payment_item_fulfillment_id": "100231",
"payment_item_fulfillment_status": "delivered",
"payment_item_return_window": "P2D",
"payment_item_url":
"https://www.sd.com/prd/12121"
}
]
}
}

auth_token
auth_token must be sent with all client requests. The auth_token is a JWT token which helps
the server to validate the request source.

payment_id (string, mandatory)

payment_id is a client generated payment id which identifies the payment being created

payment_created_time (string, mandatory)

payment_created_time (DD:MM:YYYY HH:MM:SS) is the time and day when payment was
created by payment issuer on client side

payment_issuer_info (object, mandatory)

payment_issuer_info includes details of the customer/seller/client who has created the
payment. Name of the issuer is mandatory.

Response
Status Response

200 {
"api_action_status": “success”,
"noderetail_payment_id": “12133111”
}
 auth_token (string) - all API calls must have this key in header

403 {"error":"Auth token is missing."}

401 {"error":"Invalid auth token."}

500 {"error":"Something went wrong. Please try again later."}

7. payment/request_using_onconfirm
This api will create a payment in nodepay using on_confirm payload

Request
Method URL

POST payment/request_using_onconfirm/

Type Params Values

HEAD auth_token JWT

nodesso_id string

BODY {
"nodepay_account_user_id": "string",
"nodepay_payment_instance_id": "string",
"payment_id": "6527c56454105e766fc1477c",
"payment_requested_time": "15:10:2023 22:20:50",
“on_confirm_payload”: {
“message”: {},
“context”:{}
}
}
auth_token
auth_token must be sent with all client requests. The auth_token is a JWT token which helps
the server to validate the request source.

payment_id (string, mandatory)

payment_id is a client generated payment id which identifies the payment being created

payment_created_time (string, mandatory)

payment_created_time (DD:MM:YYYY HH:MM:SS) is the time and day when payment was
created by payment issuer on client side

payment_issuer_info (object, mandatory)

payment_issuer_info includes details of the customer/seller/client who has created the
payment. Name of the issuer is mandatory.

Response
Status Response

200 {
"api_action_status": “success”,
"noderetail_payment_id": “12133111”
}

auth_token (string) - all API calls must have this key in header

403 {"error":"Auth token is missing."}

401 {"error":"Invalid auth token."}

500 {"error":"Something went wrong. Please try again later."}

8. payment/accept
This api will approve the payment created in nodepay
Request
Method URL

POST payment/accept

Type Params Values

HEAD auth_token JWT

nodesso_id string

BODY {
"payment_id": "6527c56454105e766fc1477c",
"nodepay_account_user_id":"string",
"nodepay_payment_instance_id":"string",
"nodepay_payment_id": "121222"
"payment_accept_info": {
“payment_accept_status”: ”accept/reject”,
“payment_expected”: “1000”,
“payment_accept_remarks”: “Under paid”,
"accepter_name": "Manoj",
"accepter_phone": "9879879870",
"accepter_email": "[email protected]"
}
}

auth_token
auth_token must be sent with all client requests. The auth_token is a JWT token which helps
the server to validate the request source.

payment_id (string, mandatory)

payment_id is a client generated payment id which identifies the payment being created

payment_created_time (string, mandatory)

payment_created_time (DD:MM:YYYY HH:MM:SS) is the time and day when payment was
created by payment issuer on client side
payment_issuer_info (object, mandatory)
payment_issuer_info includes details of the customer/seller/client who has created the
payment. Name of the issuer is mandatory.

Response
Status Response

200 {
"api_action_status": “success”,
“accept_remarks”: “payment will be made again”
}

auth_token (string) - all API calls must have this key in header

403 {"error":"Auth token is missing."}

401 {"error":"Invalid auth token."}

500 {"error":"Something went wrong. Please try again later."}

Addendum

How to create a JWT token for authentication?

Plotch follows JWT with JWS for signing validation and JWE for encryption where JWE is
optional. The JWT auth token needs to be passed in the header of the API call to ensure that
Noderetail can authenticate the api call using that.

JWT structure:
JWTs consist of three parts separated by dots (.), which are:
 ● Header
● Payload
● Signature

Therefore, a JWT auth token typically looks like the following: header.payload.signature

JWT creation:
The data in the Header section identifies which algorithm and token type are used to generate
the signature. For your JWT token, use RS256 and token type JWT:

alg: RS256 (string, required) - encryption algorithm;

typ: JWT (string, required) - token type;

Header:
{
"alg": "RS256",
"typ": "JWT"
}

The Payload section contains a set of claims. For your JWT, use the following claims:
● challenge_string: challenge_string (string, required) - this will be provided by Plotch
● iat: 1580915730 (string, required) - issued at, must be current timestamp since the UNIX
epoch;
Payload:
{
"challenge_string": "challenge_string",
"iat": 1580912768
}

Sign this using your private keys using RS256 signing algorithm
You will get the JWT token in this format:
eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJz...z0ZY6L6T1GvlOHiptgOQ

Use this JWT token in the header of the apis (auth_token field) to pass your identity.
JWT debugging:
For debugging and testing of JWT, please visit: https://jwt.io/
Asymmetric key exchange:

After generating the public and private keys, the public key of the client app/erp will be needed
by Noderetail to check the auth_token validity. This public key can be published on a url or
exchanged via email with the Plotch team.