1.1.5. Deposit to Card Transfer¶
Direct Integration¶
Deposit to card URL¶
The End point ID is an entry point for incoming Merchant’s transactions and is the only Industra object which is exposed via API.
Deposit to card transactions are initiated through HTTPS POST request by using URL in the following format:
https://ecom.industra.finance/paynet/api/v2/create-card-ref/ENDPOINTID – to get card-ref-id
https://ecom.industra.finance/paynet/api/v4/transfer-by-ref/ENDPOINTID – to make transfer from account to destination card-ref-id
for integration purposes use staging environment sandbox.ecom.industra.finance instead of production ecom.industra.finance
Deposit to card multi currency URL¶
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
https://ecom.industra.finance/paynet/api/v2/create-card-ref/group/ENDPOINTGROUPID – to get card-ref-id
https://ecom.industra.finance/paynet/api/v4/transfer-by-ref/group/ENDPOINTGROUPID – to make multi currency transfer from account or source card-ref-id to destination card number or destination card-ref-id
Deposit to card General Flow¶
Deposit to card is made in three steps:
- Initial payment – make initial payment sale or preauth transaction type to verify and authorize the credit card
- Card registration – get card’s reference ID card-ref-id and remember it
- Money transfer – run transfer-by-ref using card-ref-id
Process Card Registration¶
Merchant should get card-ref-id that will be used in future payments in order to avoid storing the credit card sensitive data which is required by PCI DSS. Card Registration ID is totally secure and cannot be used by fraudsters to process fraudulent transaction even if they know it. This allows to securely save card-ref-id in Customer’s profile on the Merchant’s side.
Card registration transactions are initiated through HTTPS POST request by using URL in the following format:
https://ecom.industra.finance/paynet/api/v2/create-card-ref/ENDPOINTID
for integration purposes use staging environment sandbox.ecom.industra.finance instead of production ecom.industra.finance
Card registration request parameters¶
Note
Request must have content-type=application/x-www-form-urlencoded and Authorization headers.
| Request parameters | Description |
|---|---|
| login | Merchant login name |
| client_orderid | Merchant order identifier of the transaction for which the status is requested |
| orderid | Order id assigned to the order by Industra |
| control | Checksum used to ensure that it is Industra (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control |
As you may see from the parameters list Merchant has to supply orderid and client_orderid associated with the first payment transaction. It emphasizes that the first payment is a mandatory step to process any recurrent payments.
Card Registration Response¶
Note
Response has Content-Type: text/html;charset=utf-8 header. All parameters in response are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Response parameter | Description |
|---|---|
| type | The type of response. May be create-card-ref-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details |
| status | The status code of the order. May be approved, error or filtered. It type equals filtered it means the transaction was considered fraudulent by Industra Server |
| card-ref-id | Card reference ID to used in deposit to card payments |
| unq-card-ref-id | Unique customer’s tokenized cardholder’s data ID to each PAN. It can be used by Merchant for loyalty programs or fraud control. |
| serial-number | Unique number assigned by Industra server to particular request from the Merchant |
| error-message | If status is declined or error this parameter contains the reason for decline |
| error-code | The error code is case of declined or error status |
| end-point-id | Endpoint id used for the transaction. |
Process money transfer¶
Merchant initiates transfer using given destination-card-no or destination-card-ref-id.
Industra returns new Order ID for the this transfer.
Merchant starts polling Industra by using Order Status API.
Industra returns current status of the order. processing status means the order is still being processed.
Industra processes the payment using appropriate bank’s gateway.
Merchant keeps polling Industra by using Order Status API.
Industra returns current status of the order -approved.
See more details about asynchronous status polling at Order Status API.
Money transfer request parameters¶
Transfer from account transactions are initiated through HTTPS POST request by using URL in the following format:
https://ecom.industra.finance/paynet/api/v4/transfer-by-ref/ENDPOINTID
for integration purposes use staging environment sandbox.ecom.industra.finance instead of production ecom.industra.finance
Note
Request must have content-type=application/x-www-form-urlencoded and Authorization headers.
| Money transfer request parameter | Length/Type | Comment | Necessity |
|---|---|---|---|
| client_orderid | 128/String | Merchant order identifier | Mandatory |
| login | 20/String | Merchant’s login. Must be used as oauth_consumer_key in OAuth Authorization, not included in request as login parameter | Mandatory |
| destination-card-no | 16-19/String | Card number of destination card. Mandatory if destination-card-ref-id omitted. For the scenario of payment to a card inside the system, this card will be considered as a destination, and all processing limits, lists and fraud scoring will be applied to it as a destination card. | Conditional |
| destination-card-ref-id | 20/Numeric | Card reference id to destination card, obtained at Card Registration step. Mandatory if destination-card-no omitted. For the scenario of payment to a card inside the system, this card will be considered as a destination, and all processing limits, lists and fraud scoring will be applied to it as a destination card. | Conditional |
| amount | 10/Numeric | Amount to be transferred. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents | Mandatory |
| currency | 3/String | Currency the transaction is charged in (three-letter currency code). Example ofВ valid parameter values are: USD for US Dollar EUR for European Euro | Mandatory |
| order_desc | 64k/String | Order description | Mandatory |
| receiver_identity_document_series | 512/String | Receiver’s identity document series (e.g. 4 digits for Russian Federation passport) | Optional |
| receiver_identity_document_number | 512/String | Receiver’s identity document number (e.g. 6 digits for Russian Federation passport) | Optional |
| receiver_identity_document_id | 512/String | Receiver’s identity document id. Possible values: 21 for Russian Federation passport or 31 for international passport | Optional |
| receiver_address1 | 512/String | Receiver’s address | Conditional* |
| receiver_city | 512/String | Receiver’s city | Conditional* |
| receiver_first_name | 128/String | Receiver first name | Mandatory |
| receiver_middle_name | 128/String | Receiver middle name | Optional |
| receiver_last_name | 128/String | Receiver last name | Mandatory |
| receiver_phone | 128/String | Receiver full international cell phone number, including country code | Optional |
| receiver_resident | Boolean (true/false) | Is receiver a resident? | Optional |
| ipaddress | 45/String | Customer’s IP address, included for fraud screening purposes | Optional |
| first_name | 128/String | Sender first name | Optional |
| middle_name | 128/String | Sender middle name | Optional |
| last_name | 128/String | Sender last name | Optional |
| ssn | 32/Numeric | Last four digits of the Sender’s social security number | Optional |
| birthday | 8/Numeric | Sender date of birth, in the format MMDDYY | Optional |
| address1 | 50/String | Sender address line 1 | Optional |
| city | 50/String | Sender city | Optional |
| state | 2-3/String | Sender’s state. Please see Appendix A for a list of valid state codes. Mandatory for USA, Canada and Australia | Optional |
| zip_code | 10/String | Sender ZIP code | Optional |
| receiver_zip_code | 10/String | Receiver ZIP code | Conditional* |
| country | 2/String | Sender country(two-letter country code). Please see Appendix B for a list of valid country codes | Optional |
| receiver_country_code | 2/String | Receiver country(two-letter country code). Please see Appendix B for a list of valid country codes | Optional |
| phone | 15/String | Sender full international phone number, including country code | Optional |
| cell_phone | 15/String | Sender full international cell phone number, including country code | Optional |
| 50/String | Sender email address | Optional | |
| purpose | 128/String | Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +7123456789; gamer0001@ereality.com etc. This value will be used by fraud monitoring system | Optional |
| server_callback_url | 128/String | URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks | Optional |
| redirect_url | 250/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. See more details at Statuses | Optional |
| redirect_success_url | 1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved | Optional |
| redirect_fail_url | 1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered | Optional |
| merchant_data | 64k/String | Any additional information for this transaction which may be useful in Merchant’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Merchant Callback. | Optional |
Parameters marked as Conditional* can be mandatory for specific integrations. For more information, please contact your manager in Industra.
Transfer Response¶
Note
Response has Content-Type: text/html;charset=utf-8 header. All parameters in response are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value
| Response parameter | Description |
|---|---|
| type | The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details |
| paynet-order-id | Order id assigned to the order by Industra |
| merchant-order-id | Merchant order id |
| serial-number | Unique number assigned by Industra server to particular request from the Merchant |
| error-message | If status is error this parameter contains the reason for decline or error details |
| error-code | The error code is case of error status |
Transfer Response Example¶
type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935
Transfer Request Debug¶
Enter your private key in PKCS#1 container to use debug. See OAuth RSA-SHA256 for details.
Debug form
Fillup mandatory fields (the red ones) with appropriate values. Empty values will not be included in output.
Use either destination-card-no or destination-card-ref-id
| Normalized parameters string to sign, according to OAuth 1.0a rules |
|---|
| POST body parameters to submit |
|---|
| OAuth 1.0a headers to submit. |
|---|
| HEX Encoded Signature |
|---|
| Base64 Encoded Signature |
|---|
|
Order status¶
Merchant must use Order Status API call to get the customer’s order transaction status. After any type of transaction is sent to Industra server and order id is returned, Merchant should poll for transaction status. When transaction is processed on Industra server side it returns it’s status back to Merchant and at this moment the Merchant is ready to show the customer transaction result, whether it’s approved or declined.
Recommended status polling time is 5 minutes with 3-5 seconds interval.
See more details at Statuses
Status API URL¶
Status API calls are initiated through HTTPS POST request by using URL in the following format:
https://ecom.industra.finance/paynet/api/v2/status/ENDPOINTID
for integration purposes use staging environment sandbox.ecom.industra.finance instead of production ecom.industra.finance
Order status call parameters¶
Note
Request must have content-type=application/x-www-form-urlencoded.
| Call status parameter | Description | Necessity |
|---|---|---|
| login | Merchant login name | Mandatory |
| client_orderid | Merchant order identifier of the transaction for which the status is requested | Mandatory |
| orderid | Order id assigned to the order by Industra | Conditional |
| by-request-sn | Serial number assigned to the specific request by Industra. If this field exist in status request, status response return for this specific request | Optional |
| control | Checksum used to ensure that it is Industra (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. See Order Status API call authorization through control parameter for more details about generating control checksum | Mandatory |
In most common cases, the best option is to include both client_orderid and orderid parameters to status request. Order status can be requested with only client_orderid if it’s unique to merchant and orderid is not received. If orderid is not received in response, but this response contains an error, see the received error message to get the information why transaction was not created in the system.
Order Status Response¶
Note
Response has Content-Type: text/html;charset=utf-8 header. All parameters in response are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value
| Status Response Parameter | Description |
|---|---|
| type | The type of response. May be status-response |
| status | The status code of the initial transaction. May be approved, declined, processing, error or filtered. It type equals filtered it means the transaction was considered fraudulent by Industra Server |
| amount | Actual transaction amount. This value can be changed during the transaction flow |
| paynet-order-id | Order id assigned to the order by Industra |
| merchant-order-id | Merchant order id |
| phone | Customer phone |
| serial-number | Unique number assigned by Industra server to particular request from the Merchant |
| dest-last-four-digits | Last four digits of customer credit card number |
| dest-bin | Bank BIN of customer credit card number |
| dest-card-type | Type of customer credit card (VISA, MASTERCARD, etc) |
| gate-partial-reversal | Processing gate support partial reversal (enabled or disabled) |
| gate-partial-capture | Processing gate support partial capture (enabled or disabled) |
| transaction-type | Transaction type (sale, reversal, capture, preauth) |
| processor-rrn | Bank Receiver Registration Number |
| processor-tx-id | Acquirer transaction identifier |
| receipt-id | Electronic link to receipt https://ecom.industra.finance/paynet/view-receipt/ENDPOINTID/receipt-id/ |
| destination-hash-id | Unique card identifier to use for loyalty programs or fraud checks |
| destination-card-country-alpha-three-code | Three letter country code of destination card issuer. See Country Codes for details |
| Customer e-mail | |
| first-name | Customer’s first name |
| last-name | Customer’s last name |
| country * | Customer’s country (two-letter country code). Please see Country Codes for a list of valid country codes. |
| state * | Customer’s state . Please see Country Codes for a list of valid state codes. Mandatory for USA, Canada and Australia. |
| city * | Customer’s city |
| zip_code * | Customer’s ZIP code |
| address1 * | Customer’s address line 1 |
| purpose | Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card to some type of client’s account, e.g. game or mobile phone account. Sample values are: +7123456789; gamer0001@ereality.com etc. This value will be used by fraud monitoring system |
| dest-bank-name | Bank name by customer card BIN |
| terminal-id | Acquirer terminal identifier to show in receipt |
| paynet-processing-date | Acquirer transaction processing date |
| approval-code | Bank approval code |
| order-stage | The current stage of the transaction processing. See Order Stage for details |
| loyalty-balance | The current bonuses balance of the loyalty program for current operation. if available |
| loyalty-message | The message from the loyalty program. if available |
| loyalty-bonus | The bonus value of the loyalty program for current operation. if available |
| loyalty-program | The name of the loyalty program for current operation. if available |
| descriptor | Bank identifier of the payment recipient |
| original-gate-descriptor | Descriptor, which is set on gate level in the system |
| eci | Electronic Commerce Indicator (Visa) |
| ips-dst-payment-product-code | Code for card set by multinational financial service. (Visa/Mastercard) |
| ips-dst-payment-product-name | Decrypted code for card set by multinational financial service. (Visa/Mastercard) |
| ips-dst-payment-type-code | Type of card code set by multinational financial service. (Visa/Mastercard) |
| ips-dst-payment-type-name | Decrypted code for type of card set by multinational financial service. (Visa/Mastercard) |
| error-message | If status in declined, error, filtered this parameter contains the reason for decline |
| error-code | The error code is case status in declined, error, filtered |
| by-request-sn | Serial number assigned to the specific request by Industra. If this field exist in status request, status response return for this specific request |
| initial-amount | Amount, set in initiating transaction, without any fees or commissions. This value can’t change during the transaction flow |
| seller-commission | Total commission for processed transaction. This is optional parameter. Please contact your manager in Industra, if you would like to receive it |
| acquirer-commission | Acquirer commission for processed transaction. This is optional parameter. Please contact your manager in Industra, if you would like to receive it |
| motivational-message | This is an optional message which contains extended information about the reason for the declined transaction. |
| transaction-date | Date of final status assignment for transaction. |
Note
* - these parameters are not defined by default. Please contact tech support to include these fields in callback.
Order Status Response Example¶
type=status-response
&serial-number=00000000-0000-0000-0000-00000aa68276
&merchant-order-id=pg1sbw
&processor-tx-id=15222817
&paynet-order-id=15222817
&status=approved
&amount=20000.00
&descriptor=no
&transaction-type=transfer
&receipt-id=18042926-d652-331c-b5a0-3e1dbacf69b2
&email=gmail.com
&last-name=Smith
&first-name=John
&processor-rrn=187722741
&approval-code=610669
&order-stage=transfer_approved
&phone=%2B79633014273
&dest-bank-name=SBERBANK
&dest-bin=427655
&dest-last-four-digits=7682
&dest-card-type=VISA
&paynet-processing-date=2015-04-06+22%3A00%3A27+MSK
&by-request-sn=00000000-0000-0000-0000-00000a8d3992
&destination-card-hash-id=1664889
&destination-card-country-alpha-three-code=MYS
&eci=02
&ips-dst-payment-product-code=SAP
&ips-dst-payment-product-name=SAP—Platinum Mastercard® Salary– Immediate Debit
&ips-dst-payment-type-code=Debit
&ips-dst-payment-type-name=MASTERCARD Debit
&initial-amount=20000.00
&motivational-message=Sorry, your payment has been declined.
&transaction-date=2023-01-10+12%3A46%3A28+MSK
Status request authorization through control parameter¶
The checksum is used to ensure that it is Merchant (and not a fraudster) that sends the request to Industra. This SHA-1 checksum, the parameter control, is created by concatenating of the values of the parameters in the following order:
- login
- client_orderid
- orderid
- merchant_control
For example assume the following values are corresponds the parameters above:
| Parameter Name | Parameter Value |
|---|---|
| login | cool_merchant |
| client_orderid | 5624444333322221111110 |
| orderid | 9625 |
| merchant_control | r45a019070772d1c4c2b503bbdc0fa22 |
The complete string example may look as follows:
cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22
Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for authorizing the callback. For the example control above will take the following value:
c52cfb609f20a3677eb280cc4709278ea8f7024c