Creating an HPM Payment Link

Creating an HPM Payment Link

Description

This service generates a single link per payment request using the order/transaction information coming from the site owner’s system.

When the generated link is clicked by the user, it redirects to the Finrota payment screen and completes the payment there.

• Endpoint (Demo): https://pgw.netahsilatdemo.com/hpm

• Method: POST

• Content-Type: application/json

• Authentication: Authorization: Bearer {token}

Request Body Structure

Fields and Requirement Status

General Fields

Field	Type	Required	Description
currencyCode	String	Yes	Payment currency (e.g., TRY, USD).
clientOrderReference	String	Yes	The site owner’s own order reference. It is recommended to be unique in your system.
amount	Decimal	Yes	Payment amount. Must be positive.
paymentSetId	String	Yes	Unique ID (GUID) of the payment set/scenario defined on the Finrota side.
description	String	No	Payment description. Visible on portal and reports.

Customer Information (customer)

Field	Type	Required	Description
customer.email	String	Yes	Customer’s email address. Used for notifications and communication.
customer.gsm	String	No	Customer’s GSM number. Can be used for SMS notifications.
customer.tckn	String	No	Customer’s TCKN information. For identity verification / reporting.
customer.code	String	No	Code representing the customer in the site owner’s system.
customer.name	String	No	Customer’s first name.
customer.surname	String	No	Customer’s last name.
customer.erpCode	String	No	ERP code used on the integration side.

Redirect & Notification URLs

Field	Type	Required	Description
successURL	String	No	URL to redirect the customer’s browser after a successful payment.
failURL	String	No	URL to redirect the customer’s browser after a failed/cancelled payment.
webhookURL	String	No	Webhook address used for the server-side HTTP POST call by Finrota once the payment is completed.

Important – webhookURL Field

• The webhookURL you send in the HPM request is the URL that Finrota will call server-side (callback) after the payment is completed.

• Finrota sends an HTTP POST request to this URL once the payment is processed.

• Your webhookURL endpoint is expected to return a 200 OK response. Any other response may be considered an error.

• The request body contains summary information about the payment transaction:

Field	Description
Id	Transaction ID.
TransactionStatusId	Transaction status (success, failure, etc.).
OrderReference	Order reference generated by Finrota.
ClientOrderReference	Your submitted clientOrderReference value.
PureAmount	Net collected amount.
CurrencyId	Transaction currency.
VPosErrorCode	Virtual POS error code (if any).
VPosErrorMessage	Virtual POS error message (if any).

Example Webhook Body

{

"Id": "d6a1f4b2-1c3e-4a21-9b1e-11aa22bb33cc",

"TransactionStatusId": 1,

"OrderReference": "HPM-20251201-00001",

"ClientOrderReference": "0005",

"PureAmount": 150.00,

"CurrencyId": "TRY",

"VPosErrorCode": null,

"VPosErrorMessage": null

}

On your back-end, you need to handle this POST call and read the body to update your order records as “paid/failed.”

User Verification Fields

Field	Type	Required	Description
userVerificationBy	String	Yes	Field type used for customer verification. Valid values: Id, Email, Tckn, Gsm.
userVerificationFailBehavior	String	Yes	Behavior to follow if verification fails. Example: "Create": create a new customer if the user is not found. Other options depend on portal configuration (throw error, continue with default user, etc.).

Dynamic Fields (additionalData)

Field	Type	Required	Description
additionalData	Object	No	Dictionary structure to send dynamic fields. Keys are dynamic field codes defined in Finrota. E.g.: "1606_Dinamik_Alan_tr": "4"

userVerificationBy

Specifies which field will be used to verify the customer on the Finrota side.

Possible values:

• "Id" – Verify using customer system ID

• "Email" – Verify using email address

• "Tckn" – Verify using TCKN

• "Gsm" – Verify using GSM number

userVerificationFailBehavior

Defines the system behavior if the user cannot be found according to the specified userVerificationBy field.

• Throw Error → e.g., "Error"

  • Request fails if the user cannot be found.

• Create New Customer → "Create"

  • If the user is not found, a new customer record is created on Finrota.

• Continue with Default User → (e.g., "Default" / "DefaultUser" etc.)

  • If the user is not found, the system continues with the predefined default user.

Note: The exact string values for enum options (Error, DefaultUser, etc.) will be provided to you during integration. Only "Create" is guaranteed in this example.

additionalData

• The additionalData field is used to populate dynamic fields defined on the Finrota portal.

Keys generally match the related dynamic field code/name.

Example

"additionalData": {   
  "1606_Dinamik_Alan_tr": "4",  
  "1606_dinamik_Alan_tr": "55"  
}

Example Request

Header

Authorization: Bearer {token}  
Content-Type: application/json

Body

{  
  "currencyCode": "TRY",  
  "clientOrderReference": "0005",  
  "amount": 150,  
  "customer": {  
    "email": "[email protected]",  
    "gsm": "5000000000",  
    "tckn": "00000000000",  
    "code": "13wedas12",  
    "name": "John",  
    "surname": "Doe",  
    "erpCode": "asdc123ff19"  
  },  
  "successURL": "https://webhook.free.beeceptor.com/success",  
  "failURL": "https://google.com?q=fail",  
  "webhookURL": "https://yahoo.com",  
  "paymentSetId": "504978bf-bebd-40c5-89aa-b76f3a20341c",  
  "description": "hpm test",  
  "userVerificationBy": "Id",  
  "userVerificationFailBehavior": "Create",  
  "additionalData": {  
    "1606_Dinamik_Alan_tr": "4",  
    "1606_dinamik_Alan_tr": "55"  
  }  
}

Example cURL

curl --location 'https://pgw.netahsilatdemo.com/hpm' \  
--header 'Content-Type: application/json' \  
--header 'Authorization: Bearer {token}' \  
--data '{  
  "currencyCode": "TRY",  
  "clientOrderReference": "0005",  
  "amount": 150,  
  "customer": {  
    "email": "[email protected]",  
    "gsm": "5000000000",  
    "tckn": "00000000000",  
    "code": "13wedas12",  
    "name": "John",  
    "surname": "Doe",  
    "erpCode": "asdc123ff19"  
  },  
  "successURL": "https://webhook.free.beeceptor.com/success",  
  "failURL": "https://google.com?q=fail",  
  "webhookURL": "https://yahoo.com",  
  "paymentSetId": "504978bf-bebd-40c5-89aa-b76f3a20341c",  
  "description": "hpm test",  
  "userVerificationBy": "Id",  
  "userVerificationFailBehavior": "Create",  
  "additionalData": {  
    "1606_Dinamik_Alan_tr": "4",  
    "1606_dinamik_Alan_tr": "55"  
  }  
}'

Response Model

For a successful request, HPM returns a response in the following structure:

{  
  "message": null,  
  "statusCode": 200,  
  "exceptions": null,  
  "data": {  
    "link": "https://testportal.netfinans.com/netahsilat/hpm?id=3e1c720e-baa1-4672-955f-07bad7a23133&timestamp=1764601213815&sign=b5c709a40eeeee308cf2f32a40457a2b8a8e88711352c93a4f91d109d7d23fd3",  
    "expiryUtc": "2025-12-01T15:15:13.8152725"  
  },  
  "oldData": null,  
  "errors": null  
}

Field Descriptions

• statusCode

  • Can reflect application-level status independently from HTTP. 200 → success.

• data.link

  • The single payment link where the user will be redirected.

  • Note: A single link is returned per payment request.

  • On this link, the payment screen will be displayed with the information entered during the request.

  • After redirecting to the payment screen, the payment transaction is carried out as usual.

• data.expiryUtc

  • Contains the link’s expiration date/time in UTC format.

  • Format is always ISO-8601 (e.g., "2025-12-01T15:15:13").

• sign

  • Security signature is included in the link’s query string (sign=...).

  • It is not returned as a separate field in JSON.