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 SolidPayments object which is exposed via API.

Deposit to card transactions are initiated through HTTPS POST request by using URL in the following format:
https://gate.solidpayments.com/paynet/api/v2/create-card-ref/ENDPOINTID – to get card-ref-id
https://gate.solidpayments.com/paynet/api/v4/transfer-by-ref/ENDPOINTID – to make transfer from account to destination card-ref-id
for integration purposes use staging environment sandbox.solidpayments.com instead of production gate.solidpayments.com

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://gate.solidpayments.com/paynet/api/v2/create-card-ref/group/ENDPOINTGROUPID – to get card-ref-id
https://gate.solidpayments.com/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:

  1. Initial payment – make initial payment sale, preauth, transfer or any other transaction type to verify and authorize the credit card
  2. Card registration – get card’s reference ID card-ref-id and remember it
  3. 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://gate.solidpayments.com/paynet/api/v2/create-card-ref/ENDPOINTID
for integration purposes use staging environment sandbox.solidpayments.com instead of production gate.solidpayments.com

Card registration request parameters

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 SolidPayments
control Checksum used to ensure that it is SolidPayments (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

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 SolidPayments Server.
card-ref-id Card referense ID to used in subsequent recurrent payments
serial-number Unique number assigned by SolidPayments 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

Process money transfer

Merchant initialtes transfer using given destination-card-no or destination-card-ref-id or destination-iban-no.
SolidPayments returns new Order ID for the this transfer.
Merchant starts polling SolidPayments by using Order Status API.
SolidPayments returns current status of the order. processing status means the order is still being processed.
SolidPayments processes the payment using appropriate bank’s gateway.
Merchant keeps polling SolidPayments by using Order Status API.
SolidPayments 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://gate.solidpayments.com/paynet/api/v4/transfer-by-ref/ENDPOINTID
for integration purposes use staging environment sandbox.solidpayments.com instead of production gate.solidpayments.com
Money transfer request parameter Length/Type Comment Necessity
client_orderid 128/String Merchant order identifier. Mandatory
login 20/String Merchant’s login. Mandatory
destination-card-no 16-19/String Card number of destination card. Mandatory if destination-card-ref-id:ex: ommited. Conditional
destination-iban-no 12-34/String Destination IBAN. Mandatory if both destination-card-no and destination-card-ref-id are ommited. Conditional
destination-bic 11/String Bank Identifier Code. Mandatory if destination-iban-no specified. Conditional
destination-card-ref-id 20/Numeric Card reference id to destination card, obtained at Card Registration step. Mandatory if destination-card-no ommited. Conditional
amount 10/Numeric Amount to be transfered. 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 Depending on the acquirer (e.g. for transfer amounts over 15000 rub): Receiver’s identity document series (e.g. 4 digits for Russian Federation passport). Conditional*
receiver_identity_document_number 512/String Depending on the acquirer (e.g. for transfer amounts over 15000 rub): Receiver’s identity document number (e.g. 6 digits for Russian Federation passport). Conditional*
receiver_identity_document_id 512/String Depending on the acquirer (e.g. for transfer amounts over 15000 rub): Receiver’s identity document id. Possible values: 21 for Russian Federation passport or 31 for international passport. Conditional*
receiver_address1 512/String Depending on the acquirer (e.g. for transfer amounts over 15000 rub): Receiver’s address Conditional*
receiver_city 512/String Depending on the acquirer (e.g. for transfer amounts over 15000 rub): Receiver’s city Conditional*
receiver_first_name 128/String Receiver first name. Conditional*
receiver_middle_name 128/String Receiver middle name. Conditional*
receiver_last_name 128/String Receiver last name. Conditional*
receiver_phone 128/String Receiver full international cell phone number, including country code. Conditional*
receiver_resident Boolean (true/false) Is receiver a resident? Conditional*
ipaddress 20/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
country 2/String Sender 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
email 50/String Sender email address. 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. Optional

Parameters marked as Conditional* can be mandatory for specific integrations. For more information, please contact your manager in SolidPayments.

Transfer Response

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 SolidPayments
merchant-order-id Merchant order id
serial-number Unique number assigned by SolidPayments 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

To reproduce your API call, input all of the data from your original request, including the authentication tokens. Don’t forget to set the nonce and timestamp to the values you used. An OAuth signed URL should match regardless of the generating library. If the signatures differ, you know there is a bug in your OAuth signature code. Due to current PCI DSS restrictions only OAuth 1.0a RSA-SHA256 signature is allowed. Other signature methods are restricted. So to send command to the server your request should be: sent as POST, contains OAuth 1.0a headers, signed with RSA-SHA256.

Generate Public and Private key pair

You need only private and public key to authorize your transaction. To generate it please got to https://www.openssl.org/ download latest version of openssl and run following commands:

openssl genpkey -algorithm RSA -out private_key_pkcs_8.pem -pkeyopt rsa_keygen_bits:4096
openssl rsa -pubout -in private_key_pkcs_8.pem -out public_key.pem

Share your Private key with no one, you should be the only person to know it. Your Public key, on the contrary, should be sent to your manager, so he can register it in the system. Use different keys for production and for testing purposes to avoid its comprometation.

Private key

For using this demo you need private key in PKCS#1 container. The format of the key should be PKCS#1 PEM text formatted and unencrypted RSA private key. To get it use the following command

openssl rsa -in private_key_pkcs_8.pem -out private_key_pkcs_1.pem

As a result you will get a key starting with -----BEGIN RSA PRIVATE KEY-----. For production purposes you can use key in any format supported by your software. This demo supports key length up to 4096. Insert your RSA Private key for sandbox environment below.

Debug form

Fillup mandatory fields (the red ones) with appropriate values. Empty values will not be included in output.

Use either destination-card-no, destination-card-ref-id or destination-iban-no with destination-bic.

URL input URL
login your login should be used as Consumer Public for OAuth
client_orderid make it or use your internal invoice ID
destination-card-no enter the beginning of the sequence, and then "i".
destination-card-ref-id
destination-iban-no
destination-bic
order_desc
amount
currency
ipaddress
first_name
middle_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
email
receiver_first_name
receiver_middle_name
receiver_last_name
receiver_phone
receiver_resident
receiver_identity_document_series
receiver_identity_document_number
receiver_identity_document_id
receiver_address1
receiver_city
redirect_url
server_callback_url
merchant_data

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
* HEX encoded string is for debug purposes only. You shouldn't send this string to the server neither in HEX nor in Encoded HEX representation.
Base64 Encoded Signature
* Binary RSA-SHA256 signature directly encoded in base64 should be sent to the server.

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 SolidPayments server and order id is returned, Merchant should poll for transaction status. When transaction is processed on SolidPayments 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.

Status API URL

Status API calls are initiated through HTTPS POST request by using URL in the following format:
https://gate.solidpayments.com/paynet/api/v2/status/ENDPOINTID
for integration purposes use staging environment sandbox.solidpayments.com instead of production gate.solidpayments.com

Order status call parameters

Call status parameter 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 SolidPayments
by-request-sn Serial number assigned to the specific request by SolidPayments. If this field exist in status request, status response return for this specific request.
control Checksum used to ensure that it is SolidPayments (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.

Order Status Response

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 SolidPayments Server.
amount Amount of the initial transaction.
paynet-order-id Order id assigned to the order by SolidPayments
merchant-order-id Merchant order id
phone Customer phone.
serial-number Unique number assigned by SolidPayments 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 Electronical link to receipt https://gate.solidpayments.com/paynet/view-receipt/ENDPOINTID/receipt-id/
destination-hash-id Unique card identifier to use for loyalty programs or fraud checks.
email Customer e-mail.
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.
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 from status request, if exists in request. Warning parameter amount always shows initial transaction amount, even if status is requested by-request-sn.

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
&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

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 SolidPayments. 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

Order status Debug

endpointid
login
client_orderid
orderid
merchant_control
by-request-sn

String to sign
Signature