Three-Step Redirect API

Customer Vault

Step One
Three-Step: Customer Vault

Add/Update Customer XML Request

XML Element Description
<add-customer|update-customer> Type of transaction to perform.
api-key* api-key is obtained in the security keys section of the control panel settings.
redirect-url* A URL on your web server that the gateway will redirect your customer to after sensitive data collection.
customer-vault-id Load customer details from an existing customer vault record. If set, no payment information is required during step two.
merchant-defined-field-# Merchant specified custom fields.
Format: merchant_defined_field_1=Value
<billing> The customer's billing information
billing-id Specify billing id. Required for 'update-customer' if multiple billing-ids exist, optional for 'add-billing'.
first-name Cardholder's first name.
last-name Cardholder's last name.
address1 Cardholder's billing address.
city Card billing city.
state Card billing state/province.
Format: CC
postal Card billing postal code.
country Card billing country code.
Format: CC/ISO 3166
phone Billing phone number.
email Billing email address.
company Cardholder's company.
address2 Card billing address, line 2.
fax Billing fax number.
account-type The customer's ACH account type.
Values: 'checking' or 'savings'
entity-type The customer's ACH account entity.
Values: 'personal' or 'business'
priority Specify priority (If omitted, will be auto-generated and returned in response).
Format: Numeric, 1-255
</billing>
<shipping> The customer's shipping information.
shipping-id Specify shipping id (Required for update-customer if multiple shipping-ids exist. Optional for add-billing).
first-name Shipping first name.
last-name Shipping last name.
address1 Shipping billing address.
city Shipping city.
state Shipping state/province.
Format: CC
postal Shipping postal code.
country Shipping country code.
Format: CC/ISO 3166
phone Shipping phone number.
email Shipping email address.
company Shipping company.
address2 Shipping address, line 2.
fax Shipping fax number.
priority Specify priority, if omitted, will be auto-generated and returned in response.
Format: Numeric, 1-255
</shipping>
</add-customer|update-customer>
* Required


XML Response

XML Element Description
<response>
result 1=Approved
2=Declined
3=Error in transaction data or system error
result-text Textual response.
result-code Numeric mapping of processor responses. (See Appendix 3)
form-url URL used as the action of the HTML form in step two.
</response>
Collapse Step #1

Step Two
Three-Step: Customer Vault

HTML Form Fields Request

HTML Form Fields Description
billing-cc-number* Credit card number.
billing-cc-exp* Credit card expiration.
Format: MMYY
billing-account-name** The name on the customer's ACH Account.
billing-account-number** The customer's bank account number.
billing-routing-number** The customer's bank routing number.
billing-cvv Card security code.
billing-track-1*** Raw magnetic stripe data, track 1.
billing-track-2*** Raw magnetic stripe data, track 2.
billing-track-3*** Raw magnetic stripe data, track 3.
billing-magnesafe-track-1*** Raw MagTek Magensa encrypted reader data.
billing-magnesafe-track-2*** Raw MagTek Magensa encrypted reader data.
billing-magnesafe-track-3*** Raw MagTek Magensa encrypted reader data.
billing-magnesafe-ksn*** Raw MagTek Magensa encrypted reader data.
billing-magnesafe-magneprint-status*** Raw MagTek Magensa encrypted reader data.
billing-social-security-number**** Customer's social security number (Checked against bad check writers database if check verification is enabled).
billing-drivers-license-number**** Driver's license number (Checked against bad check writers database if check verification is enabled).
billing-drivers-license-dob**** Driver's license date of birth.
billing-drivers-license-state**** Customer's driver's license state.
Format: CC
billing-micr Physical check's Magnetic ink strip (On supported check processors. For use with POP/ARC sec-code).
billing-account-type The customer's ACH account type.
Values: 'checking' or 'savings'
billing-entity-type The customer's ACH account entity.
Values: 'personal' or 'business'
billing-first-name Cardholder's first name, overwrites value if passed during step one.
billing-last-name Cardholder's last name, overwrites value if passed during step one.
billing-address1 Cardholder's billing address, overwrites value if passed during step one.
billing-city Card billing city, overwrites value if passed during step one.
billing-state Card billing state/province, overwrites value if passed during step one.
Format: CC
billing-postal Card billing postal code, overwrites value if passed during step one.
billing-country Card billing country code, overwrites value if passed during step one.
Format: CC/ISO 3166
billing-phone Billing phone number, overwrites value if passed during step one.
billing-email Billing email address, overwrites value if passed during step one.
billing-company Cardholder's company, overwrites value if passed during step one.
billing-address2 Card billing address, line 2, overwrites value if passed during step one.
billing-fax Billing fax number, overwrites value if passed during step one.
shipping-first-name Shipping first name, overwrites value if passed during step one.
shipping-last-name Shipping last name, overwrites value if passed during step one.
shipping-address1 Shipping billing address, overwrites value if passed during step one.
shipping-city Shipping city, overwrites value if passed during step one.
shipping-state Shipping state/province, overwrites value if passed during step one.
Format: CC
shipping-postal Shipping postal code, overwrites value if passed during step one.
shipping-country Shipping country code, overwrites value if passed during step one.
Format: CC/ISO 3166
shipping-phone Shipping phone number, overwrites value if passed during step one.
shipping-email Shipping email address, overwrites value if passed during step one.
shipping-company Shipping company, overwrites value if passed during step one.
shipping-address2 Shipping address, line 2, overwrites value if passed during step one.
shipping-fax Shipping fax number, overwrites value if passed during step one.
* Required for keyed credit card transactions.
** Required for ACH transactions.
*** Used for retail transactions. Variables used dependent on swipe device.
**** Required for check verification.
Required for check scanning.


HTML Form Fields Response

Once the Payment Gateway has collected the customer's sensitive payment details, the customer's browser will immediately be redirected back to the redirect-url on your web server. A variable named token-id will be appended to the redirect-url in the GET query string as described below:

https://redirect-url/?token-id=[token]


Collapse Step #2

Step Three
Three-Step: Customer Vault

Complete Action XML Request

XML Element Description
<complete-action>
api-key* api-key is obtained in the security keys section of the control panel settings.
token-id* Customer payment token returned during step two.
</complete-action>
* Required

Complete Action XML Response

XML Element Description
<response>
result 1=Transaction Approved
2=Transaction Declined
3=Error in transaction data or system error
result-text Textual response.
result-code Numeric mapping of processor responses. (See Appendix 3)
action-type Action type that was initially specified.
Values: 'sale', 'auth', 'credit', 'validate', or 'offline'
customer-vault-id Customer vault id used or created during action.
merchant-defined-field-# Merchant specified custom fields.
Format: merchant_defined_field_1=Value
<billing> The customer's billing information.
billing-id Billing id used or created for this action.
first-name Cardholder's first name.
last-name Cardholder's last name.
address1 Cardholder's billing address.
city Card billing city.
state Card billing state/province.
Format: CC
postal Card billing postal code.
country Card billing country code.
Format: CC/ISO 3166
phone Billing phone number.
email Billing email address.
company Cardholder's company.
address2 Card billing address, line 2.
fax Billing fax number.
social-security-number Customer's social security number
drivers-license-number Driver's license number.
drivers-license-dob Driver's license date of birth.
drivers-license-state Customer's driver's license state.
Format: CC
cc-number Masked credit card number.
Format: XXXXXX********XXXX
cc-exp Credit card expiration.
Format: MMYY
account-name The name on the customer's bank account.
account-number Masked bank account number.
Format: X****XXXX
routing-number Masked bank routing number.
Format: X****XXXX
account-type The customer's ACH account type.
Values: 'checking' or 'savings'
entity-type The customer's ACH account entity.
Values: 'personal' or 'business'
priority Billing id priority.
Format: Numeric, 1-255
</billing>
<shipping> The customer's shipping information.
shipping-id Shipping id used or created during action.
first-name Shipping first name.
last-name Shipping last name.
address1 Shipping billing address.
city Shipping city.
state Shipping state/province.
Format: CC
postal Shipping postal code.
country Shipping country code.
Format: CC/ISO 3166
phone Shipping phone number.
email Shipping email address.
company Shipping company.
address2 Shipping address, line 2.
fax Shipping fax number.
priority Shipping id priority.
Format: Numeric, 1-255
</shipping>
</response>
Collapse Step #3

Additional Operations
Three-Step: Customer Vault

Add/Update Billing Request (Step 1)

XML Element Description
<add-billing|update-billing> Type of transaction to perform.
api-key* api-key is obtained in the security keys section of the control panel settings.
redirect-url* A URL on your web server that the gateway will redirect your customer to after sensitive data collection.
customer-vault-id* Load customer details from an existing customer vault record. If set, no payment information is required during step two.
<billing> The customer's billing information
billing-id Specify billing id. Required for update-customer if multiple billing ids exist, optional for add-billing.
first-name Cardholder's first name.
last-name Cardholder's last name.
address1 Cardholder's billing address.
city Card billing city.
state Card billing state/province.
Format: CC
postal Card billing postal code.
country Card billing country code.
Format: CC/ISO 3166
phone Billing phone number.
email Billing email address.
company Cardholder's company.
address2 Card billing address, line 2.
fax Billing fax number.
account-type The customer's ACH account type.
Values: 'checking' or 'savings'
entity-type The customer's ACH account entity.
Values: 'personal' or 'business'
priority Specify priority (If omitted, will be auto-generated and returned in response.)
Format: Numeric, 1-255
</billing>
</add-billing|update-billing>
* Required

Customer Vault initiated Sale/Auth/Credit/Offline XML Request

Element Description
<sale|auth|credit|offline> Any and all optional fields described here can be appended to this request.
api-key* api-key is obtained in the security keys section of the control panel settings.
amount* Total amount to be charged.
Format: x.xx
processor-id If using multiple MIDs, route to this processor. The values for 'processor-id' are obtained under 'Settings'->'Load Balancing' in the Control Panel.
customer-vault-id* Load Customer details from an existing Customer Vault record.
<billing> The customer's billing information.
billing-id Load Billing ID details from an existing Billing record. If not set, the billing-id with the highest priority will be used by default.
</billing>
<shipping> The customer's shipping information.
shipping-id Load shipping id details from an existing shipping record. If unset, the billing-id with the highest priority will be used by default.
</shipping>
</sale|auth|credit|offline>
* Required

Delete Customer XML Request

Element Description
<delete-customer>
api-key* api-key is obtained in the security keys section of the control panel settings.
customer-vault-id* Specify customer to be deleted.
</delete-customer>
* Required

Delete Billing XML Request

Element Description
<delete-billing>
api-key* api-key is obtained in the security keys section of the control panel settings.
customer-vault-id* Load customer details from an existing customer vault record. If set, no payment information is required during step two.
<billing>
billing-id* Specify billing id to delete.
</billing>
</delete-billing>
* Required

Add/Update/Delete Shipping XML Request

These requests can be made the by replacing the billing section with shipping


Collapse Additional Operations



Apply for a Merchant Account Signup for the Payment Gateway


Retail & Internet Merchant Accounts

An Internet Merchant Account is sometimes referred to as a "MOTO" (Mail Order & Telephone Order) Account because they all require the ability to process a credit card payment when there is no physical credit card present to be swiped. A standard retail "swipe" merchant account does not allow processing of these "card-not-present" transactions.

View details »

High Risk Merchant Accounts

If the domestic banks are denying your merchant application because they believe your industry is considered high risk, CyoGate can help! We have an offshore network of merchant processing partners that enable us to provide low cost, high risk merchant solutions to a much wider range of businesses and industries.

View details »

Internet Payment Gateway

The CyoGate Internet Payment Gateway offers one of the quickest and most cost effective ways to accept and process credit card and electronic check payments online. Our payment gateway works with most existing merchant accounts and supports hundreds of popular web shopping carts and eCommerce platforms.

View details »