Payments

Process and manage payments from a variety of sources all within one integration.

Please, note that all requests must be signed

Charge

Charge request is the essential operation of withdrawal amounts from the cardholder's account. Upon successful withdrawal, two scenarios on this order are possible - refund or chargeback. This operation can make via 3DS. 

When the charge is successfully done, cardholder data are tokenized so that the subsequent payments can be made by the token. 

To run token-based payments, you should utilize "payment_source: type=token" and provide "payment_source: payment_token" received after successful charge. 

POST https://pay.solidgate.us/api/v3/charge


   Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idMstring(100)Order ID specified in merchant system123443334
amountMintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. 1020
currencyMstring(3)Currency amount. 3 letter currency code under ISO-4217USD
order_descriptionMstring(255)A description of the paymentPremium package
order_dateOstring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_itemsOstring(255)Order items in UTF-8 code item 1, item 2
order_numberOintegerNumber of payments by user1
subscription_product_idOstring(36)ID of the predefined product
 
faf3b86a-1fe6-4ae5-84d4-ab0651d75db2
 
callback_urlOstring(255)URL of merchant page, where response with payment result will be sent http://merchant.example/callback
fail_urlOstring(255)URL of merchant page, which a customer will be redirected in case of unsuccessful paymenthttp://merchant.example/fail
success_urlOstring(255)URL of merchant page, which a customer will be redirected in case of successful paymenthttp://merchant.example/success
settleMobject  
settle: delay_hoursMintegerTime (in hours) when auto-settle should be done 24
websiteOstring(255)Website from which transaction took placehttp://merchant.example
processing_midMstring(255)Use the processing MID parameter to route order on the chosen pathb0651d75db2
dynamic_descriptorOstring(50)The descriptor for the transactionpayhere.com
three_dsOobjectInformation required for 3D Secure payments 
three_ds: forceObooleanRouting payments flag for 3DS flow false
three_ds: attempt_non_secureObooleanDetermines whether to attempt a 3D Secure payment as non-3D Secure should the card issuer not be enrolledfalse
three_ds: mpi_dataCobjectRequired if using a third-party merchant plug-in (MPI) 
three_ds: mpi_data: cavvCstring(50)A Base64 encoded cryptographic identifier (CAVV) used by the card schemes to validate the cardholder authentication result (3D Secure). Required if using an external MPI 
three_ds: mpi_data: ds_transaction_idCstring(50)  
three_ds: mpi_data: eciCstring(2)The Electronic Commerce Indicator security level associated with the 3D Secure enrollment result. 5
three_ds: mpi_data: versionCstring(10)Indicates the version of 3D Secure that was used for authentication. Defaults to 1.0.0 if not provided
 
2.1.0
three_ds: mpidata: xidCstring(50)The 3D Secure transaction identifier. Required if using an external MPI with 3D Secure 2.X.X and a Mastercard card, or with 3D Secure 1.X.X for any supported card scheme
 
MDAwMDAwMDAwMDAwMDAwMzIyNzY
customerMobjectDetails of the customer to associate with the source 
customer: user_idMstring(100)The identifier of an existing customercuid_y343t4mf46fdzuxjbcn2giaqnb44
customer: emailMstring(100)An optional email address to associate with the customeruser@solidgate.us
customer: ip_addressMstring(50)The IP address used to make the payment. Required for some risk checks8.8.8.8
customer: first_nameOstring(100)The customer's first nameChack
customer: last_nameOstring(100)The customer's last nameBlank
customer: phone_numberOstring(50)The payment source owner's phone number+1415 555 2671
customer: date_of_birthOstring(50)Birthdate in YYYY-MM-DD format. 2000-11-21
customer: ip_countryOstring(3)ISO-code of the country that was sent in the requestUSA
customer: delivery_addressOobjectThe delivery address 
customer: delivery_address: line1Ostring(100)The delivery address line 115 William St
customer: delivery_address: line2Ostring(100)The delivery address line 2 
customer: delivery_address: cityOstring(100)City of the delivery address New York
customer: delivery_address: stateOstring(100)State of the delivery address WA
customer: delivery_address: zipOstring(10)ZIP code of the delivery address 10005
customer: delivery_address: countryOstring(3)ISO country code of the delivery address USA
recurringOobject  
recurring: typeOstring(100)Type of the recurring transaction. Possible values: 1-click/recurring/installment/retry/Nullrecurring
recurring: retry_attemptOintegerA number of retry payment1
payment_sourceMobjectThe source of the payment.
Use to request a payment
 
payment_source: typeMstring(100)The payment source type. Possible values: card|apple-pay|google-pay|tokencard
payment_source: card_numberMstring(25)The card number (without separators). Mandatory for source type card4111111111111111
payment_source: card_holder_nameMstring(32)The name of the cardholder. Mandatory for source type cardBram Fisher
payment_source: card_exp_monthMstring(2)The expiry month of the card. Mandatory for source type card10
payment_source: card_exp_yearMstring(4)The expiry year of the card Mandatory for source type card2025
payment_source: card_cvvOstring(4)The card verification value/code. 3 digits, except for Amex (4 digits)121
payment_source: payment_tokenMstring(255)The SolidGate token. Mandatory for source type tokentoken_et62tfldj6upfdvfde2reztkm54i
payment_source: billing_addressOobjectThe billing address of the cardholder 
payment_source: billing_address: line1Ostring(100)The first line of the addressSolidGate
payment_source: billing_address: line2Ostring(100)The second line of the address90 Tottenham Court Road
payment_source: billing_address: cityOstring(100)The address cityNew York
 
payment_source: billing_address: stateOstring(100)The address stateWA
payment_source: billing_address: zipOstring(10)The address zip/postal code10005
payment_source: billing_address: countryOstring(3)ISO country code of the addressUSA

Charge Request Sample | Success

{
  "order_id": "123443334",
  "amount": 50000,
  "currency": "USD",
  "order_description": "testPayment",
  "order_date": "2015-12-21 11:21:30",
  "order_items": "1",
  "order_number": 19,
  "subscription_product_id": "12345",
  "callback_url": "http://merchant.example/notification",
  "fail_url": "http://merchant.example/fail",
  "success_url": "http://merchant.example/success",
  "settle": {
    "delay_hours": 24
  },
  "website": "Website",
  "processing_mid": "12345",
  "dynamic_descriptor": "SolidGate",
  "three_ds": {
    "force": false,
    "attempt_non_secure": false,
    "mpi_data": {
      "cavv": "CAVV",
      "ds_transaction_id": "DS_ID",
      "eci": "EC",
      "version": "Version",
      "xid": "XID"
    }
  },
  "recurring": {
    "type": "1-click",
    "retry_attempt": 1
  },
  "customer": {
    "user_id": "98765",
    "email": "test@solidgate.us",
    "ip_address": "62.80.190.126",
    "first_name": "FirstName",
    "last_name": "LastName",
    "phone_number": "PhoneNumber500",
    "date_of_birth": "DateOfBirth500",
    "ip_country": "USA",
    "delivery_address": {
      "line1": "Line1",
      "line2": "Line2",
      "city": "City",
      "state": "State",
      "zip": "12334",
      "country": "USA"
    }
  },
  "payment_source": {
    "type": "card",
    "card_number": "4532456618142692",
    "card_holder_name": "Kurt Cruickshankkk",
    "card_exp_month": "03",
    "card_exp_year": "2021",
    "card_cvv": "967",
    "billing_address": {
      "line1": "SolidGate",
      "line2": "90 Tottenham Court Road",
      "city": "New York",
      "state": "WA",
      "zip": "12345",
      "country": "USA"
    }
  }
}

 

   Response Body Parameters

ParameterTypeDescriptionExample
order_idstringOrder ID specified in merchant system1234567890
currencystringCurrency amount. 3 letter currency code under ISO-4217USD
amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. 1020
refunded_amountintegerAmount of refund 500
settled_amountintegerAmount of Settle500
statusstringThe status of the paymentsettled
descriptorstringThe descriptor for the transactionSolidGate
declineobjectObject with the information about the decline  
decline: codestringDecline code4.09
decline: messagestringAn array of decline messages related to this attribute SolidGate antifraud engine
riskobjectReturns the payment's risk assessment results 
risk: decisionstringDecision by risk rule, that was applied to the order.reject
avs_checkstringAVS check result codeY
cvv_checkstringCVV check result code0
three_dsobjectProvides 3D Secure enrollment status if the payment was downgraded to non-3D Secure 
three_ds: enrolledbooleanIndicates the 3D Secure enrollment status of the issuer
three_ds: authentication_resultstringresult of the 3DS authentication 
three_ds: versionstringIndicates the version of 3D Secure that was used for authentication. Defaults to 1.0.0 if not provided
 
2.1.0
three_ds: ecistringThe Electronic Commerce Indicator security level associated with the 3D Secure enrollment result5
three_ds: xidstringThe 3D Secure transaction identifier. Required if using an external MPI with 3D Secure 2.X.X and a Mastercard card, or with 3D Secure 1.X.X for any supported card schemeMDAwMDAwMDAwMDAwMDAwMzIyNzY
three_ds: cavvstringA Base64 encoded cryptographic identifier (CAVV) used by the card schemes to validate the cardholder authentication result (3D Secure). Required if using an external MPI 
websitestringWebsite from which transaction took placehttp://merchant.example
processing_midstringUse the processing MID parameter to route order on the chosen pathb0651d75db2
subscription_idstring  
redirect_urlstringURL of merchant page, which customers will be redirected upon 3DS verification on bank end with the status of operation in URL parameterhttp://merchant.example/redirect
transactionobject  
transaction: idstringID of the transaction inside the order. Order can contain several transactions sblvku4ge3dwpztvyizgcau
transaction: created_atstringDate and time of the transaction creation 2020-04-24 7:29:20
transaction: updated_atstringDate and time of the transaction update 2020-04-24 7:29:20
transaction: operationstringTransaction typeauth
transaction: statusstringThe transaction status 
transaction: currencystringCurrency amount. 3 letter currency code under ISO-4217USD
transaction: amountintegerTransaction amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. 1020
transaction: auth_codestringThe acquirer authorization code if the payment was authorized770687
transaction: arnstringThe acquirer reference number (ARN) that you can use to query the issuing bank74548998294293193445538
transaction: refund_reason_codestringRefund reason - 4 digit code, specified in the refund reason list0012
payment_sourceobject  
payment_source: typestringThe payment source type. Possible values: card|apple-pay|google-pay|tokencard
payment_source: token_expiration_datestringDate of SolidGate token expiration2020-08-14 08:56:55
payment_source: payment_tokenstringThe SolidGate token. Mandatory for source type token.token_et62tfldj6upfdvfde2reztkm54i
payment_source: issuerstringThe name of the card issuerGOTHAM STATE BANK
payment_source: binstringThe card issuer's bank identification number (BIN)444455
payment_source: card_brandstringCard brandVISA
payment_source: card_typestringThe card type
Possible values: Credit | Debit | Prepaid | Charge
Credit
payment_source: card_exp_monthstringThe expiry month10
payment_source: card_exp_yearstringThe expiry year2025
payment_source: card_holder_namestringCardholder name Bram Fisher
payment_source: masked_card_numberstringThe masked card number

 
444455XXXXXX6666
payment_source: issuer_countrystringThe card issuer's countryUSA
payment_source: billing_addressobjectThe billing address of the cardholder 
payment_source: billing_address: line1stringThe first line of the addressSolidGate
payment_source: billing_address: line2stringThe second line of the address90 Tottenham Court Road
payment_source: billing_address: citystringThe address cityNew York
 
payment_source: billing_address: statestringThe address stateWA
payment_source: billing_address: zipstringThe address zip/postal code10005
payment_source: billing_address: countrystringISO country code of the of the addressUSA

Charge Response Sample | Success

{
    "currency": "USD",
    "amount": 50000,
    "refunded_amount": 0,
    "settled_amount": 0,
    "status": "processing",
    "descriptor": "FAKE_TWO",
    "order_id": "1597648587705",
    "website": "website",
    "processing_mid": "12345",
    "subscription_id": "card-subcription-1",
    "payment_source": {
        "type": "card",
        "issuer": "CITIZENS STATE BANK",
        "bin": 453245,
        "card_brand": "VISA",
        "card_type": "DEBIT",
        "card_exp_month": "03",
        "card_exp_year": "2021",
        "card_holder_name": "kurt cruickshankkk",
        "masked_card_number": "453245XXXXXX2692",
        "issuer_country": "USA",
        "billing_address": {
            "line1": "NALLine1",
            "line2": " adsaLine2",
            "city": "Casdity",
            "state": "MI",
            "zip": "12asd345dd",
            "country": "USA"
        }
    },
    "transaction": {
        "id": "1eafb6997ab98ea41e0469237edc8a425f3a2eccc06d0",
        "created_at": "2020-08-17 07:16:28",
        "updated_at": "2020-08-17 07:16:28",
        "operation": "auth",
        "status": "created",
        "currency": "USD",
        "amount": 50000
    }
}

When you submit invalid API request, you would receive a response with the following body parameters. 

 

ParameterTypeDescriptionExample
errorobjectObject with information on errors 
error:codestringSolidGate code of the validation error2.01
error: messagesobjectObject with error list 
error:messages:<attribute_name>stringAttribute name where the error was foundcurrency
error:messages:<error_message>arrayThe array of error messages relating to the respective attributeThis value should have exactly 3 characters.

Charge Request Sample | Fail

{
    "error": {
        "code": "2.01",
        "messages": {
            "currency": [
                "This value should have exactly 3 characters."
            ]
        }
    }
}

Apple Pay

Start seamlessly accepting credit card payments and eliminate the need for your customers to type card and shipping details manually. Apple Pay payments are authorized through Touch ID and Face ID.

The merchant must obtain its own ApplePay certificate. The merchant must pay for and have an active Apple account, and an Apple merchant ID must be created. 

Below are the required actions to be completed in order to obtain the ApplePay certificates from Apple: 

Apple Pay Certification

  1. Log in to https://developer.apple.com/
  2. Click on the Certificates, IDs & Profiles option.
  3. From the newly opened screen select Merchant IDs and click on the (+) button.
  4. Select an ID and enter a short description.
  5. Once the ID is created, a confirmation screen appears. It is recommended that the merchant ensures that the entered data is valid.
  6. Click the Register button. If the registration is successful a screen showing ‘Registration complete’ appears.
  7. Click on the row with the newly created ID and choose the Edit button and the options to create Identity and Payment Processing Certificates are shown. On this page, the process of adding/verifying domains can be started.

Creating a Payment Processing Certificate

  1. From the Edit screen of the Merchant IDs panel choose the "Create Certificate" button.
  2. Answer “No” to the question “Will payments associated with this Merchant ID be processed exclusively in China?” and click “Continue”. The next screen contains the instruction on how to create the CSR (and the accompanying it public and private keys).
  3. Get certificate by signing request (.csr) file from SolidGate Support. This is the file that needs to be uploaded to Apple’s web page.
  4. From the Browse dialogue choose the file by clicking on the “Choose File” button and click “Continue”. If the certificate is successfully created, a screen will appear allowing the signed .cer file to be downloaded. Click on the “Download” button and save the file to the disk.
  5. The Payment Processing Certificate (with a .cer extension) must be sent to SolidGate Support.

Creating an Identity Certificate
The identity certificate is needed when merchants want to process Apple Pay payments that originate from within a web page since Apple needs to verify the ownership of the domain from which the payment is initialized. One identity certificate may be used to identify multiple domains.

  1. From Merchant IDs select the desired ID for creating the identity certificate. Choose the Create Certificate button found in the Merchant Identity Certificate box.
  2. The steps for creating and exporting the certificates are the same as for Payment Processing Certificates with the only difference being that the following type should be chosen: Key Size – 2048 bits; Algorithm: RSA.

Adding Domains to the Apple Merchant ID
To use the “Apple Pay on the Web” each of the domains from which the payment request will be made should be verified. The verification is done by uploading a file on a specified location on the merchant’s website.

  1. Select the Add Domain button from the Merchant IDs screen and the Register Merchant Domain window appears
    NOTE: There are a few requirements to the server on which the domain runs (e.g. the merchant server must support the TLS 1.2 protocol and the pages must be served via https). More information can be found here: https://developer.apple.com/reference/applepayjs. The above link also contains a complete guide on how to verify the domain.
  2. From the Register Merchant Domain window enter the desired domain to be verified and should press Continue.
  3. Download the file generated by Apple and upload it to the path shown on the screen.
  4. Once the file is uploaded the client must click on the Verify button. The uploaded file must be publicly accessible via https.

Integrate with Apple Pay

To process Apple Pay payments, you must configure your Apple Developer account, complete the certification process, and enhance your iOS app or website to have the capability to access Apple Pay payments.
For Apple Pay configuration resources, please refer to the following:

Devices which work with apple pay

Liability shift on Apple Pay

Apple Pay transactions using Mastercard and American Express enjoy a liability shift to the card issuer — similar to 3-D secure transactions. Please be aware that although this is a known practice, the issuers are not bound by these terms and can change the liability agreement at any time.

 

   Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idMstring(100)Order ID specified in merchant system123443334
amountMintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. 1020
currencyMstring(3)Currency amount. 3 letter currency code under ISO-4217USD
order_descriptionMstring(255)A description of the paymentPremium package
order_dateOstring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_itemsOstring(255)Order items in UTF-8 code item 1, item 2
order_numberOintegerNumber of payments by user1
subscription_product_idOstring(36)The ID of the predefined product
 
faf3b86a-1fe6-4ae5-84d4-ab0651d75db2
 
callback_urlOstring(255)URL of merchant page, where response with payment result will be sent http://merchant.example/callback
settleMobject  
settle: delay_hoursMintegerTime (in hours) when auto-settle should be done 24
websiteOstring(255)The website from which transaction took placehttp://merchant.example
processing_midMstring(255)Use the processing MID parameter to route order on the chosen pathb0651d75db2
customerMobjectDetails of the customer to associate with the source 
customer: user_idMstring(100)The identifier of an existing customercuid_y343t4mf46fdzuxjbcn2giaqnb44
customer: emailMstring(100)An optional email address to associate with the customeruser@solidgate.us
customer: ip_addressMstring(50)The IP address used to make the payment. Required for some risk checks8.8.8.8
customer: first_nameOstring(100)The customer's first nameChack
customer: last_nameOstring(100)The customer's last nameBlank
customer: phone_numberOstring(50)The payment source owner's phone number+1415 555 2671
customer: date_of_birthOstring(50)Birthdate in YYYY-MM-DD format2000-11-21
customer: ip_countryOstring(3)ISO-code of the country that was sent in the requestUSA
customer: delivery_addressOobjectThe delivery address 
customer: delivery_address: line1Ostring(100)The delivery address line 115 William St
customer: delivery_address: line2Ostring(100)The delivery address line 2 
customer: delivery_address: cityOstring(100)City of the delivery address New York
customer: delivery_address: stateOstring(100)State of the delivery address WA
customer: delivery_address: zipOstring(10)ZIP code of the delivery address 10005
customer: delivery_address: countryOstring(3)ISO country code of the delivery address USA
payment_sourceMobjectThe source of the payment.
Use to request a payment
 
payment_source: typeMstring(100)The payment source type. 
Need to use apple-pay source for Apple Pay payments
apple-pay
payment_source: signatureMstringSignature of the payment and header data. The signature includes the signing certificate, its intermediate CA certificate, and information about the signing algorithm1UdDwEB/wQEAwIHgDAPBgkqh...92ICIAR2
payment_source: versionMstringVersion information about the payment tokenEC_v1
payment_source: dataMstringEncrypted payment dataqIEHeSmLKw3C5...ZIuf2oPeLhQ1DCaQj
payment_source: headerMobjectAn object with header information.  
payment_source: header : transactionIdMstringTransaction identifier, generated on the device7126df4ff8ac61dc60278b5cd549cc98d16b8f41
payment_source: header: publicKeyHashMstringHash of the X.509 encoded public key bytes of the merchant’s certificate mQaQhyhrXX3ZDSQv...ByX0iii0MVHthSQiXQ=
 
payment_source: header: wrappedKeyCstringThe symmetric key wrapped using your RSA public key ( Mandatory if the version is RSA_v1 only)  
payment_source: header: ephemeralPublicKeyCstringEphemeral public key bytes. (Mandatory if the version is EC_v1 only)  
payment_source: header: applicationDataOstringHash of the applicationData property of the original PKPaymentRequest object 
payment_source: networkOstringCard brand VISA, MASTERCARD

Apple Pay Request Sample

{
    "order_id": "1234567890",
    "amount": "2200",
    "currency": "USD",
    "order_description": "testPayment",
    "order_date": "2015-12-21 11:21:30",
    "order_items": "1",
    "order_number": 789,
    "subscription_product_id": "12345",
    "callback_url": "http://merchant.example/callback",
    "settle": {
        "delay_hours": 24
    },
    "website": "Website",
    "processing_mid": "12345",
    "dynamic_descriptor": "SolidGate",
    "customer" : {
        "user_id": "98765",
	    "email": "test@solidgate.us",
	    "ip_address": "62.80.190.126",
	    "first_name": "FirstName",
	    "last_name": "LastName",
	    "phone_number": "PhoneNumber500",
	    "date_of_birth": "DateOfBirth500",
	    "ip_country": "NLD",
	    "delivery_address":{
		    "line1": "Line1",
		    "line2": "Line2",
		    "city": "City",
		    "state": "State",
		    "zip": "Zip",
		    "country": "ESP"
	    }
    },
    "payment_source":{
	"type": "apple-pay",
        "signature": "1",
        "version": "1",
        "data": "1",
        "header": {
            "transactionId": "1",
            "publicKeyHash": "1",
            "wrappedKey": "1",
            "ephemeralPublicKey": "1",
            "applicationData": "1"
        },
        "network": "1"
    }
}

 

   Response Body Parameters

ParameterTypeDescriptionExample
order_idstringOrder ID specified in merchant system1234567890
currencystringCurrency amount. 3 letter currency code under ISO-4217USD
amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. 1020
refunded_amountintegerAmount of Refund 500
settled_amountintegerAmount of Settle500
statusstringThe status of the payment. settled
descriptorstringThe descriptor for the transactionSolidGate
declineobjectObject with the information about the decline  
decline: codestringDecline code4.09
decline: messagestringAn array of decline messages related to this attribute SolidGate antifraud engine
riskobjectReturns the payment's risk assessment results 
risk: decisionstringThe decision by risk rule, that was applied to the orderreject
avs_checkstringAVS check result codeY
cvv_checkstringCVV check result code0
websitestringThe website from which transaction took place. http://merchant.example
processing_midstringUse the processing MID parameter to route order on the chosen pathb0651d75db2
subscription_idstring  
redirect_urlstringURL of merchant page, which customers will be redirected upon 3DS verification on bank end with the status of the operation in URL parameterhttp://merchant.example/redirect
transactionobject  
transaction: idstringID of the transaction inside the order. Order can contain several transactions sblvku4ge3dwpztvyizgcau
transaction: created_atstringDate and time of the transaction creation 2020-04-24 7:29:20
transaction: updated_atstringDate and time of the transaction update 2020-04-24 7:29:20
transaction: operationstringTransaction typeauth
transaction: statusstringThe transaction statussuccess
transaction: currencystringCurrency amount. 3 letter currency code under ISO-4217USD
transaction: amountintegerTransaction amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. 1020
transaction: auth_codestringThe acquirer authorization code if the payment was authorized770687
transaction: arnstringThe acquirer reference number (ARN) that you can use to query the issuing bank74548998294293193445538
transaction: refund_reason_codestringRefund reason - 4 digit code, specified in the refund reason list. 0012
payment_sourceobject  
payment_source: typestringThe payment source type. Possible values: card|apple-pay|google-pay|tokencard
payment_source: token_expiration_datestringDate of SolidGate token expiration2020-08-14T08:56:55Z
payment_source: payment_tokenstringThe SolidGate token. Mandatory for source type token.token_et62tfldj6upfdvfde2reztkm54i
payment_source: issuerstringThe name of the card issuerGOTHAM STATE BANK
payment_source: binstringThe card issuer's bank identification number (BIN)444455
payment_source: card_brandstringCard brand. VISA
payment_source: card_typestringThe card type
Possible values: Credit | Debit | Prepaid | Charge
Credit
payment_source: card_exp_monthstringThe expiry month10
payment_source: card_exp_yearstringThe expiry year2025
payment_source: card_holder_namestringCardholder name Bram Fisher
payment_source: masked_card_numberstringThe masked card number

 
444455XXXXXX6666
payment_source: issuer_countrystringThe card issuer's countryUSA
payment_source: billing_addressobjectThe billing address of the cardholder 
payment_source: billing_address: line1stringThe first line of the addressSolidGate
payment_source: billing_address: line2stringThe second line of the address90 Tottenham Court Road
payment_source: billing_address: citystringThe address cityNew York
 
payment_source: billing_address: statestringThe address stateWA
payment_source: billing_address: zipstringThe address zip/postal code10005
payment_source: billing_address: countrystringISO country code of the of the addressUSA

Apple Pay Response Sample | Success

{
    "currency": "USD",
    "amount": 2200,
    "refunded_amount": 0,
    "settled_amount": 0,
    "status": "processing",
    "descriptor": "FAKE_TWO",
    "order_id": "1597422821525",
    "website": "website",
    "processing_mid": "12345",
    "subscription_id": "apple-subscription-1",
    "payment_source": {
        "type": "apple-pay",
        "card_brand": "1",
        "card_exp_year": "0",
        "card_holder_name": "firstname lastname"
    },
    "transaction": {
        "id": "051e3f696f1a86104a77f1f32d0f853e5f36bce5c341d",
        "created_at": "2020-08-14 16:33:41",
        "updated_at": "2020-08-14 16:33:41",
        "operation": "auth",
        "status": "created",
        "currency": "USD",
        "amount": 2200
    }
}

Google Pay™

By integrating Google Pay into your website or Android application, your customers can securely make one-touch payments using any credit or debit card connected to their Google account.

To start processing Google Pay™ payments, you must first register with Google. Once the integration is complete, you can add the 'Google Pay™' button to your checkout page and start requesting your customers' encrypted payment information.

For information on integrating with Google Pay, first, refer to the Google Pay API guide,Google Pay Web integration checklist,Google Pay Web Brand Guidelines,Google Pay Android integration checklist andGoogle Pay Android brand guidelines.

When you submit a payment data request to the Google API, be sure to include the following parameters:

'gateway': 'solid'
'gatewayMerchantId': '<replace with key from SolidGate>'

Google Pay API Request Sample

{
  apiVersion: 2,
  apiVersionMinor: 0,
  allowedPaymentMethods: [{
    type: 'CARD',
    parameters: {
      allowedAuthMethods: [
        'PAN_ONLY',
        'CRYPTOGRAM_3DS'
      ],
      allowedCardNetworks: [
        'AMEX',
        'DISCOVER',
        'MASTERCARD',
        'VISA'
      ]
    },
    tokenizationSpecification: {
      type: 'PAYMENT_GATEWAY',
      parameters: {
        'gateway': 'solid',
        'gatewayMerchantId': '<replace with key from SolidGate>'
      }
    }
  }]
}

To receive key you must send request for your account manager.

 

  Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idMstring(100)Order ID specified in merchant system123443334
amountMintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. 1020
currencyMstring(3)Currency amount. 3 letter currency code under ISO-4217USD
order_descriptionMstring(255)A description of the paymentPremium package
order_dateOstring(50)Date of order creation in format YYYY-MM-DD-HH-MM-SS2015-12-21 11:21:30
order_itemsOstring(255)Order items in UTF-8 code item 1, item 2
order_numberOintegerNumber of payments by user1
subscription_product_idOstring(36)ID of the predefined product
 
faf3b86a-1fe6-4ae5-84d4-ab0651d75db2
 
callback_urlOstring(255)URL of merchant page, where response with payment result will be sent http://merchant.example/callback
settleMobject  
settle: delay_hoursMintegerTime (in hours) when auto-settle should be done 24
websiteOstring(255)Website from which transaction took place. http://merchant.example
processing_midMstring(255)Use the processing MID parameter to route order on the chosen pathb0651d75db2
customerMobjectDetails of the customer to associate with the source 
customer: user_idMstring(100)The identifier of an existing customer. cuid_y343t4mf46fdzuxjbcn2giaqnb44
customer: emailMstring(100)An optional email address to associate with the customeruser@solidgate.us
customer: ip_addressMstring(50)The IP address used to make the payment. Required for some risk checks8.8.8.8
customer: first_nameOstring(100)The customer's first name. Chack
customer: last_nameOstring(100)The customer's last name. Blank
customer: phone_numberOstring(50)The payment source owner's phone number+1415 555 2671
customer: date_of_birthOstring(50)Birthdate in YYYY-MM-DD format. 2000-11-21
customer: ip_countryOstring(3)ISO-code of the country that was sent in the requestUSA
customer: delivery_addressOobjectThe delivery address 
customer: delivery_address: line1Ostring(100)The delivery address line 115 William St
customer: delivery_address: line2Ostring(100)The delivery address line 2 
customer: delivery_address: cityOstring(100)City of the delivery address New York
customer: delivery_address: stateOstring(100)State of the delivery address WA
customer: delivery_address: zipOstring(10)ZIP code of the delivery address 10005
customer: delivery_address: countryOstring(3)ISO country code of the delivery address USA
payment_sourceMobjectThe source of the payment.
Use to request a payment.
 
payment_source: typeMstring(100)The payment source type. 
Need to use google-pay source for Google Pay™ payments
google-pay
payment_source: signatureMstringVerifies the message came from Google. The signature is created using ECDSA 
payment_source: protocolVersionMstringIdentifies which encryption/signing scheme this message has been created. In this way, the protocol can evolve over time if needed. If it is not set, assume ECv0 
payment_source: signedMessageMstringA serialized JSON string containing the encryptedMessage, ephemeralPublicKey, and tag. To simplify the signature verification process, this value is serialized 

Google Pay Request Sample

{
    "order_id": "1234567890",
    "amount": 2200,
    "currency": "USD",
    "order_description": "testPayment",
    "order_date": "2015-12-21 11:21:30",
    "order_items": "12345",
    "order_number": 1234,
    "subscription_product_id": "12345",
    "callback_url": "http://merchant.example/callback",
    "settle": {
        "delay_hours": 24
    },
    "website": "Website",
    "processing_mid": "12345",
    "customer" : {
        "user_id": "98765",
	    "email": "test@solidgate.us",
	    "ip_address": "62.80.190.126",
	    "first_name": "FirstName",
	    "last_name": "LastName",
	    "phone_number": "PhoneNumber500",
	    "date_of_birth": "DateOfBirth500",
	    "ip_country": "NLD",
	    "delivery_address":{
		    "line1": "Line1",
		    "line2": "Line2",
		    "city": "City",
		    "state": "State",
		    "zip": "Zip",
		    "country": "ESP"
	    }
    },
    "payment_source":{
	"type": "google-pay",
        "signature": "1",
        "protocolVersion": "1",
        "signedMessage": "1"
}
}

Parameters of a successful response for Google Pay™ transactions are the same as for Apple Pay.

Settle

Settle method is used for settling an authorization transaction that was previously performed.

POST https://pay.solidgate.us/api/v3/settle

  

   Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idMstring(100)Order ID specified in merchant system123443334
amountMintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. 1020

Parameters of a successful response are the same as for Charge operation.

Settle Response Sample | Success

{
    "currency": "USD",
    "amount": 50000,
    "refunded_amount": 0,
    "settled_amount": 100,
    "status": "settled",
    "descriptor": "FAKE_TWO",
    "order_id": "1597648194427",
    "website": "website",
    "processing_mid": "12345",
    "subscription_id": "12345",
    "payment_source": {
        "type": "card",
        "token_expiration_date": "2021-03-31 00:00:00",
        "payment_token": "44db2bc07e1e66ee68739f733ce300415b61dfa166eaf8ebb221e49f3c098bb091548991493761684b476b3b027d8ab7f75a",
        "issuer": "CITIZENS STATE BANK",
        "bin": 453245,
        "card_brand": "VISA",
        "card_type": "DEBIT",
        "card_exp_month": "03",
        "card_exp_year": "2021",
        "card_holder_name": "kurt cruickshankkk",
        "masked_card_number": "453245XXXXXX2692",
        "issuer_country": "USA",
        "billing_address": {
            "line1": "NALLine1",
            "line2": " adsaLine2",
            "city": "Casdity",
            "state": "NY",
            "zip": "12asd345dd",
            "country": "USA"
        }
    },
    "transaction": {
        "id": "4484c5e7519841e999ba2561ddd6693a5f3a2d5711776",
        "created_at": "2020-08-17 07:10:15",
        "updated_at": "2020-08-17 07:10:15",
        "operation": "settle",
        "status": "success",
        "currency": "USD",
        "amount": 100,
        "auth_code": "6a4febf054"
    }
}

In case you try to settle the order with the statuses settle, void or refunded, you receive an error with the information that order status doesn`t fit for settle operation.

Settle Response Sample | Fail

{
    "error": {
        "code": "2.01",
        "messages": {
            "status": [
                "Illegal order status for settle operation."
            ]
        }
    }
}

Void

Voids a payment if supported by the payment method. For card payments, void requests are processed synchronously. 

POST https://pay.solidgate.us/api/v3/void

The void method is used to cancel an authorization transaction that was previously performed.

Please, note that you can void only the full order amount. 

 

   Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idMstring(100)Order ID specified in merchant system123443334

Void Request Sample

{
    "order_id": "1596722969341"
}

Parameters of a successful response are the same as for Charge operation.

Void Response Sample | Success

{
    "currency": "USD",
    "amount": 50000,
    "refunded_amount": 0,
    "settled_amount": 0,
    "status": "voided",
    "descriptor": "FAKE_TWO",
    "order_id": "1597649591433",
    "website": "website",
    "processing_mid": "12345",
    "subscription_id": "12345",
    "payment_source": {
        "type": "card",
        "token_expiration_date": "2021-03-31 00:00:00",
        "payment_token": "555692cf8f94fc63e13e40914776383793f527a8ee1d8d3fe8f3d5da636c2d840a7c17be134455b37a1178e62e0f2a57eb22",
        "issuer": "CITIZENS STATE BANK",
        "bin": 453245,
        "card_brand": "VISA",
        "card_type": "DEBIT",
        "card_exp_month": "03",
        "card_exp_year": "2021",
        "card_holder_name": "kurt cruickshankkk",
        "masked_card_number": "453245XXXXXX2692",
        "issuer_country": "USA",
        "billing_address": {
            "line1": "NALLine1",
            "line2": " adsaLine2",
            "city": "Casdity",
            "state": "NY",
            "zip": "12asd345dd",
            "country": "USA"
        }
    },
    "transaction": {
        "id": "2db1e40a5e530a4b096dcb52f60418105f3a32c07ec68",
        "created_at": "2020-08-17 07:33:20",
        "updated_at": "2020-08-17 07:33:20",
        "operation": "void",
        "status": "success",
        "currency": "USD",
        "amount": 50000,
        "auth_code": "fd7db52f05"
    }
}

Refund

Refund method allows you to refund a charge that has previously been settled but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged.

POST https://pay.solidgate.us/api/v3/refund

 

   Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idMstring(100)Order ID specified in merchant system123443334
amountMintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. 1020

Parameters of a successful response are the same as for Charge operation.

Refund Response Sample | Success

{
    "currency": "USD",
    "amount": 50000,
    "refunded_amount": 800,
    "settled_amount": 50000,
    "status": "settled",
    "descriptor": "FAKE_TWO",
    "order_id": "1597662186805",
    "website": "website",
    "processing_mid": "12345",
    "subscription_id": "12345",
    "payment_source": {
        "type": "card",
        "token_expiration_date": "2021-03-31 00:00:00",
        "payment_token": "fc2b8d42a03d6e01398aa74fb61534fed35b3a06384c3d7fd59e46db9fdf2dde896fef55dfd01bddc0ae1c0c988dd4ad8686",
        "issuer": "CITIZENS STATE BANK",
        "bin": 453245,
        "card_brand": "VISA",
        "card_type": "DEBIT",
        "card_exp_month": "03",
        "card_exp_year": "2021",
        "card_holder_name": "kurt cruickshankkk",
        "masked_card_number": "453245XXXXXX2692",
        "issuer_country": "USA",
        "billing_address": {
            "line1": "NALLine1",
            "line2": " adsaLine2",
            "city": "Casdity",
            "state": "TX",
            "zip": "12asd345dd",
            "country": "USA"
        }
    },
    "transaction": {
        "id": "6b6d2280384a86f38a66de4653b960f35f3a63f669549",
        "created_at": "2020-08-17 11:03:18",
        "updated_at": "2020-08-17 11:03:18",
        "operation": "refund",
        "status": "success",
        "currency": "USD",
        "amount": 800
    }
}

Check Order Status

Check order status is the request for getting current order status. 
 

POST https://pay.solidgate.us/api/v3/status

 

   Request Body Parameters

ParameterMandatoryTypeDescriptionExample
order_idMstring(100)Order ID specified in merchant system123443334

Status Request Sample

{
    "order_id": "1596722969341"
}

 

   Response Body Parameters

ParameterTypeDescriptionExample
order_idstringOrder ID specified in merchant system1234567890
currencystringCurrency amount. 3 letter currency code under ISO-4217USD
amountintegerOrder amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. 1020
refunded_amountintegerAmount of refund 500
settled_amountinteger 500
statusstringThe status of the payment. settled
descriptorstringThe descriptor for the transactionSolidGate
declineobjectObject with the information about the decline  
decline: codestringDecline code4.09
decline: messagestringAn array of decline messages related to this attribute SolidGate antifraud engine
riskobjectReturns the payment's risk assessment results 
risk: decisionstringDecision by risk rule, that was applied to the orderreject
avs_checkstringAVS check result codeY
cvv_checkstringCVV check result code0
three_dsobjectProvides 3D Secure enrollment status if the payment was downgraded to non-3D Secure 
three_ds: enrolledbooleanIndicates the 3D Secure enrollment status of the issuer
three_ds: authentication_resultstringresult of the 3DS authentication 
three_ds: versionstringIndicates the version of 3D Secure that was used for authentication. Defaults to 1.0.0 if not provided
 
2.1.0
three_ds: ecistringThe Electronic Commerce Indicator security level associated with the 3D Secure enrollment result5
three_ds: xidstringThe 3D Secure transaction identifier. Required if using an external MPI with 3D Secure 2.X.X and a Mastercard card, or with 3D Secure 1.X.X for any supported card schemeMDAwMDAwMDAwMDAwMDAwMzIyNzY
three_ds: cavvstringA Base64 encoded cryptographic identifier (CAVV) used by the card schemes to validate the cardholder authentication result (3D Secure). Required if using an external MPI 
websitestringWebsite from which transaction took placehttp://merchant.example
processing_midstringUse the processing MID parameter to route order on the chosen pathb0651d75db2
subscription_idstringSubscription identifier 
redirect_urlstringURL of merchant page, which customers will be redirected upon 3DS verification on bank end with the status of operation in URL parameterhttp://merchant.example/redirect
transactionsarrayThe array with List of transactions  
transactions: {id}objectThe object with information about unique transaction 
transactions: {id}: idstringID of the transaction inside the order. Order can contain several transactions sblvku4ge3dwpztvyizgcau
transactions: {id}: created_atstringDate and time of the transaction creation 2020-04-24 7:29:20
transactions: {id}: updated_atstringDate and time of the transaction update 2020-04-24 7:29:20
transactions: {id}: operationstringTransaction type auth
transactions: {id}: statusstringThe transaction status 
transactions: {id}: currencystringCurrency amount. 3 letter currency code under ISO-4217USD
transactions: {id}: amountintegerTransaction amount - integer without fractional component (i.e cents). For instance, 1020 means 10 USD and 20 cents. 1020
transactions: {id}: auth_codestringThe acquirer authorization code if the payment was authorized770687
transactions: {id}: arnstringThe acquirer reference number (ARN) that you can use to query the issuing bank74548998294293193445538
transactions: {id}: refund_reason_codestringRefund reason - 4 digit code, specified in the refund reason list. 0012
payment_sourceobject  
payment_source: typestringThe payment source type. Possible values: card|apple-pay|google-pay|tokencard
payment_source: token_expiration_datestringDate of SolidGate token expiration2020-08-14 08:56:55
payment_source: payment_tokenstringThe SolidGate token. Mandatory for source type token.token_et62tfldj6upfdvfde2reztkm54i
payment_source: issuerstringThe name of the card issuerGOTHAM STATE BANK
payment_source: binstringThe card issuer's bank identification number (BIN)444455
payment_source: card_brandstringCard brandVISA
payment_source: card_typestringThe card type
Possible values: Credit | Debit | Prepaid | Charge
Credit
payment_source: card_exp_monthstringThe expiry month10
payment_source: card_exp_yearstringThe expiry year2025
payment_source: card_holder_namestringCardholder name Bram Fisher
payment_source: masked_card_numberstringThe masked card number

 
444455XXXXXX6666
payment_source: issuer_countrystringThe card issuer's countryUSA
payment_source: billing_addressobjectThe billing address of the cardholder 
payment_source: billing_address: line1stringThe first line of the addressSolidGate
payment_source: billing_address: line2stringThe second line of the address90 Tottenham Court Road
payment_source: billing_address: citystringThe address cityNew York
 
payment_source: billing_address: statestringThe address stateWA
payment_source: billing_address: zipstringThe address zip/postal code10005
payment_source: billing_address: countrystringISO country code of the of the addressUSA

Status Response Sample

{
    "currency": "USD",
    "amount": 50000,
    "refunded_amount": 0,
    "settled_amount": 100,
    "status": "settled",
    "descriptor": "FAKE_TWO",
    "order_id": "1597648194427",
    "website": "website",
    "processing_mid": "12345",
    "subscription_id": "12345",
    "payment_source": {
        "type": "card",
        "token_expiration_date": "2021-03-31 00:00:00",
        "payment_token": "44db2bc07e1e66ee68739f733ce300415b61dfa166eaf8ebb221e49f3c098bb091548991493761684b476b3b027d8ab7f75a",
        "issuer": "CITIZENS STATE BANK",
        "bin": 453245,
        "card_brand": "VISA",
        "card_type": "DEBIT",
        "card_exp_month": "03",
        "card_exp_year": "2021",
        "card_holder_name": "kurt cruickshankkk",
        "masked_card_number": "453245XXXXXX2692",
        "issuer_country": "USA",
        "billing_address": {
            "line1": "NALLine1",
            "line2": " adsaLine2",
            "city": "Casdity",
            "state": "NY",
            "zip": "12asd345dd",
            "country": "USA"
        }
    },
    "transactions": {
        "4484c5e7519841e999ba2561ddd6693a5f3a2d5711776": {
            "id": "4484c5e7519841e999ba2561ddd6693a5f3a2d5711776",
            "created_at": "2020-08-17 07:10:15",
            "updated_at": "2020-08-17 07:10:15",
            "operation": "settle",
            "status": "success",
            "currency": "USD",
            "amount": 100,
            "auth_code": "6a4febf054"
        },
        "4484c5e7519841e999ba2561ddd6693a5f3a2d42bd9e2": {
            "id": "4484c5e7519841e999ba2561ddd6693a5f3a2d42bd9e2",
            "created_at": "2020-08-17 07:09:54",
            "updated_at": "2020-08-17 07:09:55",
            "operation": "auth",
            "status": "success",
            "currency": "USD",
            "amount": 50000,
            "auth_code": "6a4febf054"
        }
    }
}