Sending payment

The payment creation request is sent after the user has filled in all the required fields for the selected payment method. There are two types of payments: PAY_IN (deposits) and PAY_OUT (payouts).

Swagger - detailed payment API.

Mechanism of operation

1. The user fills out the form with data according to the fields of the previously obtained payment method. After that, the user confirms the form (by clicking Confirm/Pay, etc.).
2. Depending on the type of payment method (PAY_IN or PAY_OUT), the merchant sends a payment creation request:
   • POST request to https://{firstpay_url}/api/payments/v1/pay_in - for deposit payments.
   • POST request to https://{firstpay_url}/api/payments/v1/pay_out - payment for payout.
3. If the request pertains to a payment system (such as BKash, etc.), the request can include "successRedirectUrl" and "failureRedirectUrl" - URLs to which the user will be redirected after interacting with the payment system. Otherwise, the response will have a 200 status code.
4. Some payments may require SMS confirmation, more details can be found here.

API

To submit a deposit payment: POST request https://{firstpay_url}/api/payments/v1/pay_in.

To submit a payout payment: POST request https://{firstpay_url}/api/payments/v1/pay_out.

Request body interface for payment creation

{
   "publicKey": "string",
   "hash": "string",
   "accountId": 0,
   "paymentMethodId": "string",
   "amount": 0,
   "clientFieldsValues": [
      {
         "key": "string",
         "value": "string"
      }
   ],
   "merchantPaymentId": "string", // optional
   "merchantUserId": "string", // optional
   "successRedirectUrl": "string", // optional
   "failureRedirectUrl": "string", // optional
   "postBackUrl": "string", // optional
   "attachmentId": "string" // optional
}

Table describing all fields in the request body

Field						Type	Required	Description
publicKey						String	Yes	The public key issued during merchant registration on the FirstPay platform (the key is provided in a file; the entire contents of the file must be included).
hash						String	Yes	Encoded string of the request body. For instructions on how to generate it, see the "Authorization" section.
accountId						Number	Yes	Account Id received in the payment method.
paymentMethodId						String	Yes	Payment method Id.
amount						Number	Yes	Payment amount.
clientFieldsValues						Array	Yes	List of fields filled out by the user. All these fields are received within the payment method.
	key					String	Yes	Field identifier/Id.
	value					String	Yes	Value entered by the user.
merchantPaymentId						String	No	Optional field. You can specify the payment Id from your own system.
merchantUserId						String	No	Optional field. You can specify the user Id from your own system.
redirectUrl						String	No	Optional field. If redirectUrl is specified, FirstPay will redirect to the provided URL after the payment is created.
postBackUrl						String	No	Optional field. When postBackUrl is specified, FirstPay will send a request to the provided URL after the payment is confirmed. If this parameter is not provided, the request will be sent to the URL registered on the merchant's page.
attachmentId						String	No	If the payment method’s isAttachmentRequired field is set to true, this field becomes mandatory. You must upload an image as proof of payment — see the "Media Upload" section. The response will include an id field, which must be specified when creating the payment.

Table of returned responses:

code	Response body	Description
200	Response body	Upon a successful request, data for the created payment is returned.
400	{"error": "some text here..."}	An error occurs if the request body and query parameters could not be parsed (most likely due to incorrect formatting).
401	{"error": "NO_LOGIN"}	An error occurs if the publicKey field is not included in the request body.
401	{"error": "NO_TOKEN"}	An error occurs if the hash field is not included in the request body.
401	{"error": "NO_KEY"}	An error occurs if an incorrect publicKey is provided.
401	{"error": "UNAUTHORIZED"}	An error occurs if there is a validation failure for publicKey and hash.
403	{"error": "ACCESS_DENIED"}	An error occurs if the merchant specifies a payment method in the request to which they do not have access.
404	{"error": "NOT_FOUND"}	An error occurs when requesting a payment method by ID if the method does not exist in the system.
500	{"error": "some text here..."}	An error occurs when the server fails to process the request due to an unexpected situation.

Payment creation response body interface:

{
   "isSucceed": true,
   "formUrl": "string",
   "paymentId": "string",
   "info": {
      "isSMSRequired": true, // optional
      "instruction": "string" || null, // optional
      "withDeepLink": "boolean", // optional
      "showQR": "boolean", // optional
      "deepLink": { // optional
         "paytm": "string" || null, // optional
         "phonepe": "string" || null, // optional
         "gpay": "string" || null // optional
      } || null
   }
}

Table describing all fields:

Field						Type	Description
isSucceed						Boolean	Success.
formUrl						String	Optional field, present if the payment was created based on a payment system.
paymentId						String	Payment id in the FirstPay system.
info						Object	An object containing additional information.
	isSMSRequired					Boolean	Optional field. Whether an additional request for payment confirmation via SMS is required.
	instruction					String	Optional field. Comment from the payment receiving system.
	withDeepLink					Boolean	Optional field. Whether Deeplink works for payment, and whether to display a button for the user to go to the application.
	showQR					Boolean	Optional field. Whether QR code display on the payment page.
	deepLink					Object	Optional field. An object with links of payment applications. If link is defined, the corresponding button for transition to the payment application (deep link) should be displayed.
		paytm				String	Link for Paytm.
		phonepe				String	Link for Phonepe.
		gpay				String	Link for Ggpay.