Skip to content

Latest commit

 

History

History
1073 lines (952 loc) · 29.9 KB

payment.md

File metadata and controls

1073 lines (952 loc) · 29.9 KB
Raw

Payments

Capture payment

instance.payments.capture(paymentId, amount, currency)

Parameters:

Name Type Description
paymentId* string Id of the payment to capture
amount* integer The amount to be captured (should be equal to the authorized amount, in paise)
currency* string The currency of the payment (defaults to INR)

Response:

{
  "id": "pay_G8VQzjPLoAvm6D",
  "entity": "payment",
  "amount": 1000,
  "currency": "INR",
  "status": "captured",
  "order_id": "order_G8VPOayFxWEU28",
  "invoice_id": null,
  "international": false,
  "method": "upi",
  "amount_refunded": 0,
  "refund_status": null,
  "captured": true,
  "description": "Purchase Shoes",
  "card_id": null,
  "bank": null,
  "wallet": null,
  "vpa": "gaurav.kumar@exampleupi",
  "email": "gaurav.kumar@example.com",
  "contact": "+919999999999",
  "customer_id": "cust_DitrYCFtCIokBO",
  "notes": [],
  "fee": 24,
  "tax": 4,
  "error_code": null,
  "error_description": null,
  "error_source": null,
  "error_step": null,
  "error_reason": null,
  "acquirer_data": {
    "rrn": "033814379298"
  },
  "created_at": 1606985209
}

Fetch all payments

instance.payments.all(option)

Parameters:

Name Type Description
from timestamp timestamp after which the payments were created
to timestamp timestamp before which the payments were created
count integer number of payments to fetch (default: 10)
skip integer number of payments to be skipped (default: 0)
expand[] string Used to retrieve additional information about the payment. Possible value is cards or emi

Response:

{
  "entity": "collection",
  "count": 2,
  "items": [
    {
      "id": "pay_G8VaL2Z68LRtDs",
      "entity": "payment",
      "amount": 900,
      "currency": "INR",
      "status": "captured",
      "order_id": "order_G8VXfKDWDEOHHd",
      "invoice_id": null,
      "international": false,
      "method": "netbanking",
      "amount_refunded": 0,
      "refund_status": null,
      "captured": true,
      "description": "Purchase Shoes",
      "card_id": null,
      "bank": "KKBK",
      "wallet": null,
      "vpa": null,
      "email": "gaurav.kumar@example.com",
      "contact": "+919999999999",
      "customer_id": "cust_DitrYCFtCIokBO",
      "notes": [],
      "fee": 22,
      "tax": 4,
      "error_code": null,
      "error_description": null,
      "error_source": null,
      "error_step": null,
      "error_reason": null,
      "acquirer_data": {
        "bank_transaction_id": "0125836177"
      },
      "created_at": 1606985740
    }
  ]
}

Fetch a payment

instance.payments.fetch(paymentId)

Parameters:

Name Type Description
paymentId* string Id of the payment to be retrieved
expand[] string Used to retrieve additional information about the payment. Possible value is cards, emi or offers

Response:

{
  "id": "pay_G8VQzjPLoAvm6D",
  "entity": "payment",
  "amount": 1000,
  "currency": "INR",
  "status": "captured",
  "order_id": "order_G8VPOayFxWEU28",
  "invoice_id": null,
  "international": false,
  "method": "upi",
  "amount_refunded": 0,
  "refund_status": null,
  "captured": true,
  "description": "Purchase Shoes",
  "card_id": null,
  "bank": null,
  "wallet": null,
  "vpa": "gaurav.kumar@exampleupi",
  "email": "gaurav.kumar@example.com",
  "contact": "+919999999999",
  "customer_id": "cust_DitrYCFtCIokBO",
  "notes": [],
  "fee": 24,
  "tax": 4,
  "error_code": null,
  "error_description": null,
  "error_source": null,
  "error_step": null,
  "error_reason": null,
  "acquirer_data": {
    "rrn": "033814379298"
  },
  "created_at": 1606985209
}

Fetch payments for an order

instance.orders.fetchPayments(orderId)

Parameters

Name Type Description
orderId* string The id of the order to be retrieve payment info

Response:

{
  "count": 1,
  "entity": "collection",
  "items": [
    {
      "id": "pay_DovGQXOkPBJjjU",
      "entity": "payment",
      "amount": 600,
      "currency": "INR",
      "status": "captured",
      "order_id": "order_DovFx48wjYEr2I",
      "method": "netbanking",
      "amount_refunded": 0,
      "refund_status": null,
      "captured": true,
      "description": "A Wild Sheep Chase is a novel by Japanese author Haruki Murakami",
      "card_id": null,
      "bank": "SBIN",
      "wallet": null,
      "vpa": null,
      "email": "gaurav.kumar@example.com",
      "contact": "+919999999999",
      "fee": 70,
      "tax": 10,
      "error_code": null,
      "error_description": null,
      "error_source": null,
      "error_step": null,
      "error_reason": null,
      "notes": [],
      "acquirer_data": {
        "bank_transaction_id": "0125836177"
      },
      "created_at": 1400826750
    }
  ]
}

Update a payment

instance.payments.edit(paymentId,{
	"notes": {
		"key1": "value1",
		"key2": "value2"
	}
})

Parameters:

Name Type Description
paymentId* string Id of the payment to update
notes* object A key-value pair

Response:

{
  "id": "pay_CBYy6tLmJTzn3Q",
  "entity": "payment",
  "amount": 1000,
  "currency": "INR",
  "status": "authorized",
  "order_id": null,
  "invoice_id": null,
  "international": false,
  "method": "netbanking",
  "amount_refunded": 0,
  "refund_status": null,
  "captured": false,
  "description": null,
  "card_id": null,
  "bank": "UTIB",
  "wallet": null,
  "vpa": null,
  "email": "testme@acme.com",
  "notes": {
    "key1": "value1",
    "key2": "value2"
  },
  "fee": null,
  "tax": null,
  "error_code": null,
  "error_description": null,
  "error_source": null,
  "error_step": null,
  "error_reason": null,
  "acquirer_data": {
    "bank_transaction_id": "0125836177"
  },
  "created_at": 1553504328
}

Fetch expanded card or emi details for payments

Request #1: Card

instance.payments.all({'expand[]':'card'})

Response:

{
  "entity":"collection",
  "count":2,
  "items":[
    {
      "id":"pay_DG4a4vAWvKrh79",
      "entity":"payment",
      "amount":200010,
      "currency":"INR",
      "status":"authorized",
      "order_id":null,
      "invoice_id":null,
      "international":false,
      "method":"card",
      "amount_refunded":0,
      "refund_status":null,
      "captured":false,
      "description":null,
      "card_id":"card_DG4a4zHtV31t56",
      "card":{
        "id":"card_DG4a4zHtV31t56",
        "entity":"card",
        "name":"gaurav",
        "last4":"9003",
        "network":"Visa",
        "type":"credit",
        "issuer":"ICIC",
        "international":false,
        "emi":false,
        "sub_type": "business"
      },
      "bank":null,
      "wallet":null,
      "vpa":null,
      "email":"gaurav@example.com",
      "contact":"+91997200005",
      "notes":[],
      "fee":null,
      "tax":null,
      "error_code": null,
      "error_description": null,
      "error_source": null,
      "error_step": null,
      "error_reason": null,
      "acquirer_data": {
        "auth_code": "828553"
      },
      "created_at":1568026102
    }
  ]
}

Request #2: EMI

instance.payments.all({'expand[]':'emi'})

Response:

{
  "entity":"collection",
  "count":2,
  "items":[
    {
      "id":"pay_DG4ZdRK8ZnXC3k",
      "entity":"payment",
      "amount":200000,
      "currency":"INR",
      "status":"authorized",
      "order_id":null,
      "invoice_id":null,
      "international":false,
      "method":"emi",
      "amount_refunded":0,
      "refund_status":null,
      "captured":false,
      "description":null,
      "card_id":"card_DG4ZdUO3xABb20",
      "bank":"ICIC",
      "wallet":null,
      "vpa":null,
      "email":"gaurav@example.com",
      "contact":"+919972000005",
      "notes":[],
      "fee":null,
      "tax":null,
      "error_code": null,
      "error_description": null,
      "error_source": null,
      "error_step": null,
      "error_reason": null,
      "emi":{
        "issuer":"ICIC",
        "rate":1300,
        "duration":6
      },
      "acquirer_data": {
        "auth_code": "828553"
      },
      "created_at":1568026077
    }
  ]
}

Fetch card details with paymentId

instance.payments.fetchCardDetails(paymentId)

Parameters:

Name Type Description
paymentId* string Id of the payment to update

Response:

{
  "id": "card_6krZ6bcjoeqyV9",
  "entity": "card",
  "name": "Gaurav",
  "last4": "3335",
  "network": "Visa",
  "type": "debit",
  "issuer": "SBIN",
  "international": false,
  "emi": null,
  "sub_type": "business"
}

Fetch Payment Downtime Details

instance.payments.fetchPaymentDowntime()

Response:
For payment downtime response please click here

Fetch Payment Downtime

instance.payments.fetchPaymentDowntimeById(downtimeId)

Parameters:

Name Type Description
downtimeId* string Id to fetch payment downtime

Response: For payment downtime by id response please click here

Payment capture settings API

instance.orders.create({
  "amount":50000,
  "currency": "INR",
  "receipt": "rcptid_11",
  "payment": {
    "capture ": "automatic",
    "capture_options ": {
      "automatic_expiry_period ": 12,
      "manual_expiry_period ": 7200,
      "refund_speed": "optimum"
    }  
  }
})

Parameters:

Name Type Description
amount* integer Amount of the order to be paid
currency* string Currency of the order. Currently only INR is supported.
receipt string Your system order reference id.
payment object please refer this doc for params

Response: 

{
  "id": "order_DBJOWzybf0sJbb",
  "entity": "order",
  "amount": 50000,
  "amount_paid": 0,
  "amount_due": 50000,
  "currency": "INR",
  "receipt": "rcptid_11",
  "status": "created",
  "attempts": 0,
  "notes": [],
  "created_at": 1566986570
}

Create Payment Json

instance.payments.createPaymentJson({
  "amount": 100,
  "currency": "INR",
  "order_id": "order_EAkbvXiCJlwhHR",
  "email": "gaurav.kumar@example.com",
  "contact": 9090909090,
  "method": "card",
  "card":{
    "number": 4111111111111111,
    "name": "Gaurav",
    "expiry_month": 11,
    "expiry_year": 23,
    "cvv": 100
  }
})

Parameters:

Name Type Description
amount* integer Amount of the order to be paid
currency* string The currency of the payment (defaults to INR)
order_id* string The unique identifier of the order created.
email* string Email of the customer
contact* string Contact number of the customer
method* string Possible value is card, netbanking, wallet,emi, upi, cardless_emi, paylater.
card array All keys listed here are supported
bank string Bank code of the bank used for the payment. Required if the method is netbanking.
bank_account array All keys listed here are supported
vpa string Virtual payment address of the customer. Required if the method is upi.
wallet string Wallet code for the wallet used for the payment. Required if the method is wallet.
notes array A key-value pair

Response: 

{
  "razorpay_payment_id": "pay_FVmAstJWfsD3SO",
  "next": [
    {
      "action": "redirect",
      "url": "https://api.razorpay.com/v1/payments/FVmAtLUe9XZSGM/authorize"
    },
    {
      "action": "otp_generate",
      "url": "https://api.razorpay.com/v1/payments/pay_FVmAstJWfsD3SO/otp_generate?track_id=FVmAtLUe9XZSGM&key_id=<YOUR_KEY_ID>"
    }
  ]
}

OTP Generate

var instance = new Razorpay({ key_id: "key", key_secret: ""}) // Use only razorpay key

instance.payments.otpGenerate(paymentId)

Parameters:

Name Type Description
paymentId* integer Unique identifier of the payment

Doc reference doc

Response: 

{
 "razorpay_payment_id": "pay_FVmAstJWfsD3SO",
 "next": [
  {
   "action": "otp_submit",
   "url": "https://api.razorpay.com/v1/payments/pay_FVmAstJWfsD3SO/otp_submit/ac2d415a8be7595de09a24b41661729fd9028fdc?key_id=<YOUR_KEY_ID>"
  },
  {
   "action": "otp_resend",
   "url": "https://api.razorpay.com/v1/payments/pay_FVmAstJWfsD3SO/otp_resend/json?key_id=<YOUR_KEY_ID>"
  }
 ],
 "metadata": {
  "issuer": "HDFC",
  "network": "MC",
  "last4": "1111",
  "iin": "411111"
 }
}

OTP Submit

instance.payments.otpSubmit(paymentId,{
  "otp": "12345"
})

Parameters:

Name Type Description
paymentId* integer Unique identifier of the payment
otp* string The customer receives the OTP using their preferred notification medium - SMS or email

Doc reference doc

Response:
Success

{
 "razorpay_payment_id": "pay_D5jmY2H6vC7Cy3",
 "razorpay_order_id": "order_9A33XWu170gUtm",
 "razorpay_signature": "9ef4dffbfd84f1318f6739a3ce19f9d85851857ae648f114332d8401e0949a3d"
}

Failure

{
  "error": {
    "code" : "BAD_REQUEST_ERROR",
    "description": "payment processing failed because of incorrect otp"
  },
  "next": ["otp_submit", "otp_resend"]
}

OTP Resend

instance.payments.otpResend(paymentId)

Parameters:

Name Type Description
paymentId* integer Unique identifier of the payment

Doc reference doc

Response: 

{
  "next": [
    "otp_submit",
    "otp_resend"
  ],
  "razorpay_payment_id": "pay_JWaNvYmrx75sXo"
}

Create Payment Json (Third party validation)

instance.payments.createPaymentJson({
  "amount": "500",
  "currency": "INR",
  "email": "gaurav.kumar@example.com",
  "contact": "9123456789",
  "order_id": "order_GAWN9beXgaqRyO",
  "method": "netbanking",
  "bank": "HDFC"
});

Parameters:

Name Type Description
amount* integer Amount of the order to be paid
currency* string The currency of the payment (defaults to INR)
order_id* string The unique identifier of the order created.
email* string Email of the customer
contact* string Contact number of the customer
method* string Possible value is netbanking
bank* string The customer's bank code.For example, HDFC.

please refer this doc for params

Response: 

{
  "razorpay_payment_id": "pay_GAWOYqPlvrtPSi",
  "next": [
    {
      "action": "redirect",
      "url": "https://api.razorpay.com/v1/payments/pay_GAWOYqPlvrtPSi/authorize"
    }
  ]
}

Create Payment UPI s2s / VPA token (Third party validation)

instance.payments.createUpi({
  "amount": 200,
  "currency": "INR",
  "order_id": "order_GAWRjlWkVcRh0V",
  "email": "gaurav.kumar@example.com",
  "contact": "9123456789",
  "method": "upi",
  "customer_id": "cust_EIW4T2etiweBmG",
  "save": 1,
  "ip": "192.168.0.103",
  "referer": "http",
  "user_agent": "Mozilla/5.0",
  "description": "Test flow",
  "notes": {
    "note_key": "value1"
  },
  "upi": {
    "flow": "collect",
    "vpa": "gauravkumar@exampleupi",
    "expiry_time": 5
  }
});

Parameters:

Name Type Description
amount* integer Amount of the order to be paid
currency* string The currency of the payment (defaults to INR)
order_id* string The unique identifier of the order created.
email* string Email of the customer
customer_id* string The id of the customer to be fetched
contact* string Contact number of the customer
notes array A key-value pair
description string Descriptive text of the payment.
save boolean Specifies if the VPA should be stored as tokens.Possible value is 0, 1
callback_url string URL where Razorpay will submit the final payment status.
ip* string The client's browser IP address. For example 117.217.74.98
referer* string Value of referer header passed by the client's browser. For example, https://example.com/
user_agent* string Value of user_agent header passed by the client's browser. For example, Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36
upi* (for Upi only) array All keys listed here are supported

Response: 

{
  "razorpay_payment_id": "pay_EAm09NKReXi2e0"
}

Create Payment UPI s2s / VPA token (Third party validation)

instance.payments.createUpi({
    "amount": 100,
    "currency": "INR",
    "order_id": "order_Ee0biRtLOqzRjP",
    "email": "gaurav.kumar@example.com",
    "contact": "9090909090",
    "method": "upi",
    "ip": "192.168.0.103",
    "referer": "http",
    "user_agent": "Mozilla/5.0",
    "description": "Test flow",
    "notes": {
      "purpose": "UPI test payment"
    },
    "upi": {
      "flow" : "intent"
    }
});

Parameters:

Name Type Description
amount* integer Amount of the order to be paid
currency* string The currency of the payment (defaults to INR)
order_id* string The unique identifier of the order created.
email* string Email of the customer
customer_id* string The id of the customer to be fetched
contact* string Contact number of the customer
notes array A key-value pair
description string Descriptive text of the payment.
save boolean Specifies if the VPA should be stored as tokens.Possible value is 0, 1
callback_url string URL where Razorpay will submit the final payment status.
ip* string The client's browser IP address. For example 117.217.74.98
referer* string Value of referer header passed by the client's browser. For example, https://example.com/
user_agent* string Value of user_agent header passed by the client's browser. For example, Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130 Safari/537.36
upi* (for Upi only) array All keys listed here are supported

Response: 

{
  "razorpay_payment_id": "pay_CMeM6XvOPGFiF",
  "link": "upi://pay?pa=success@razorpay&pn=xyz&tr=xxxxxxxxxxx&tn=gourav&am=1&cu=INR&mc=xyzw"
}

Valid VPA (Third party validation)

instance.payments.validateVpa({
  "vpa": "gauravkumar@exampleupi"
});

Parameters:

Name Type Description
vpa* string The virtual payment address (VPA) you want to validate. For example, gauravkumar@exampleupi

please refer this doc for params

Response: 

{
  "vpa": "gauravkumar@exampleupi",
  "success": true,
  "customer_name": "Gaurav Kumar"
}

Fetch payment methods (Third party validation)

var instance = new Razorpay({ key_id: "key", key_secret: ""}); // // Use Only razorpay key

instance.payments.fetchPaymentMethods();

Response:
please refer this doc for response

Token IIN API

var tokenIin = "412345";

instance.iins.fetch(tokenIin);

Parameters:

Name Type Description
tokenIin* string The token IIN.

Response:

{
  "iin": "412345",
  "entity": "iin",
  "network": "Visa",
  "type": "credit",
  "sub_type": "business",
  "issuer_code": "HDFC",
  "issuer_name": "HDFC Bank Ltd",
  "international": false,
  "is_tokenized": true,
  "card_iin": "411111",
  "emi":{
     "available": true
     },
  "recurring": {
     "available": true
     },
  "authentication_types": [
   {
       "type":"3ds"
   },
   {
       "type":"otp"
   }
  ]
}

Fetch a Payment (With Expanded Card Details)

var paymentId = "pay_MLzFlOC98cJmHQ";

instance.payments.fetch(paymentId, {"expand[]": "card"});
Name Type Description
paymentId* integer Unique identifier of the payment
expand[] string Use to expand the card details when the payment method is card.

Response:

{
  "id": "pay_H9oR0gLCaVlV6m",
  "entity": "payment",
  "amount": 100,
  "currency": "INR",
  "status": "failed",
  "order_id": "order_H9o58N6qmLYQKC",
  "invoice_id": null,
  "terminal_id": "term_G5kJnYM9GhhLYT",
  "method": "card",
  "amount_refunded": 0,
  "refund_status": null,
  "captured": false,
  "description": null,
  "card_id": "card_H9oR0ocen1cmZq",
  "card": {
    "id": "card_H9oR0ocen1cmZq",
    "entity": "card",
    "name": "Gaurav",
    "last4": "1213",
    "network": "RuPay",
    "type": "credit",
    "issuer": "UTIB",
    "international": false,
    "emi": false,
    "sub_type": "business"
  },
  "bank": null,
  "wallet": null,
  "vpa": null,
  "email": "gaurav.kumar@example.com",
  "contact": "+919000090000",
  "notes": {
    "email": "gaurav.kumar@example.com",
    "phone": "09000090000"
  },
  "fee": null,
  "tax": null,
  "error_code": "BAD_REQUEST_ERROR",
  "error_description": "Card issuer is invalid",
  "error_source": "customer",
  "error_step": "payment_authentication",
  "error_reason": "incorrect_card_details",
  "acquirer_data": {
    "auth_code": null,
    "authentication_reference_number": "100222021120200000000742753928"
  },
  "created_at": 1620807547
}

Fetch a Payment (With Expanded Offers Details)

var paymentId = "pay_MLzFlOC98cJmHQ";

instance.payments.fetch(paymentId, {"expand[]": "emi"});

Parameters:

Name Type Description
paymentId* integer Unique identifier of the payment
expand[] string Use to expand the emi details when the payment method is emi.

Response: 

{
  "id": "pay_DG4ZdRK8ZnXC3k",
  "entity": "payment",
  "amount": 200000,
  "currency": "INR",
  "status": "authorized",
  "order_id": null,
  "invoice_id": null,
  "international": false,
  "method": "emi",
  "amount_refunded": 0,
  "refund_status": null,
  "captured": false,
  "description": null,
  "card_id": "card_DG4ZdUO3xABb20",
  "bank": "ICIC",
  "wallet": null,
  "vpa": null,
  "email": "gaurav@example.com",
  "contact": "+919972000005",
  "notes": [],
  "fee": null,
  "tax": null,
  "error_code": null,
  "error_description": null,
  "error_source": null,
  "error_step": null,
  "error_reason": null,
  "emi": {
    "issuer": "ICIC",
    "rate": 1300,
    "duration": 6
  },
  "acquirer_data": {
    "auth_code": "828553"
  },
  "created_at": 1568026077
}

Fetch a Payment (With Expanded UPI Details)

var paymentId = "pay_MLzFlOC98cJmHQ";

instance.payments.fetch(paymentId, {"expand[]": "upi"});

Parameters:

Name Type Description
paymentId* integer Unique identifier of the payment
expand[] string Use to expand the UPI details when the payment method is upi.

Response: 

{
  "id": "pay_DG4ZdRK8ZnXC3k",
  "entity": "payment",
  "amount": 100,
  "currency": "INR",
  "status": "captured",
  "order_id": "order_GjCr5oKh4AVC51",
  "invoice_id": null,
  "international": false,
  "method": "upi",
  "amount_refunded": 0,
  "refund_status": null,
  "captured": true,
  "description": "Payment for Adidas shoes",
  "card_id": null,
  "bank": null,
  "wallet": null,
  "vpa": "gaurav.kumar@upi",
  "email": "gaurav.kumar@example.com",
  "contact": "9000090000",
  "customer_id": "cust_K6fNE0WJZWGqtN",
  "token_id": "token_KOdY$DBYQOv08n",
  "notes": [],
  "fee": 1,
  "tax": 0,
  "error_code": null,
  "error_description": null,
  "error_source": null,
  "error_step": null,
  "error_reason": null,
  "acquirer_data": {
    "rrn": "303107535132"
  },
  "created_at": 1605871409,
  "upi": {
    "payer_account_type": "credit_card",
    "vpa": "gaurav.kumar@upi",
    "flow": "in_app"
  }
}

PN: * indicates mandatory fields

For reference click here