Transaction data is sent to our system from the back-end of the Merchant's server by software written or installed by the merchant. This gives the Merchant the ability to completely customize and integrate real time payment processing into his own application. To implement a Direct Mode client, familiarity with sockets and network programming is required.
A transaction is initiated by sending an HTTP POST to our host. The host will respond momentarily with the transaction result on the same socket. All data is URL encoded, just like a standard <form> POST from a browser.
Host | Port | Path | Description |
secure.netbilling.com |
1401 (http1) 1402 (https) |
/gw/sas/getid3.2 | ID generator |
/gw/sas/direct3.2 | Transaction interface | ||
/gw/sas/settle3.2 | Batch settlement interface | ||
1403 | / | VerisignTM 3 compatibility (not documented here) |
Parameter | Value |
pay_type | C |
tran_type | A |
account_id | 110006559149 |
card_number | 4444333322221186 |
card_expire | 0909 |
amount | 5.00 |
We can expect to receive the following parameters back in the response:
Parameter | Value |
status_code | ? |
trans_id | ? |
auth_code | ? |
auth_date | ? |
auth_msg | ? |
avs_code | ? |
cvv2_code | ? |
ticket_code | ? |
See the Protocol Response Reference section for more information.
First, the URL encoded HTTP POST request is assembled and sent to secure.netbilling.com port 1401:
That's all it takes to execute a basic transaction. In Unix/Linux environments, netcat(1) or nc(1) can be used to recreate this example.
For example, the minimum required parameters for a Credit Card Sale are: account_id, tran_type, pay_type, amount, card_number, card_expire, card_cvv2, bill_name1, bill_name2, bill_street, bill_zip and bill_country.
Transaction Type Table | |||
---|---|---|---|
tran_type = | Required | Optional, commonly used | Special |
"A" (auth1) |
account_id tran_type <payment information> <customer information> |
trans_id <purchase information> <shipping information> <level 2 information> |
dynip_sec_code <membership>3 <recurring billing>3 |
"S" (sale1) |
account_id tran_type <payment information> <customer information> |
trans_id <purchase information> <shipping information> <level 2 information> | |
"R" (refund1) |
account_id tran_type orig_id |
trans_id amount <purchase information> | |
"C" (credit1) |
account_id tran_type <payment information> <customer information> |
trans_id <purchase information> | |
"D" (capture1) |
account_id tran_type orig_id |
amount | |
"U" (undo1) |
account_id tran_type orig_id | ||
"Q" (quasi1) |
account_id tran_type <payment information> <customer information> |
trans_id <purchase information> <shipping information> <level 2 information> | |
"B" (batch settle2) |
account_id tran_type pay_type |
Request Parameter Definition Table | ||
---|---|---|
General parameters | ||
Parameter | Max Field Size | Description |
account_id | 12 | This is the number of your merchant or agent account, as a 12 digit string. Required for all transactions. |
site_tag | 12 |
The site tag of your website or retail site, as was configured within the system. This field is optional.
It is used to select which email receipt templates will be used, as well as for accounting purposes.
When using the membership/subscription features, site_tag is required and determines which site the new member will belong to. It can optionally contain a comma separated list of multiple site_tags. The new member will be a primary member of the first site_tag in the list, and a secondary member of each additional site specified. |
affiliate_tag | 12 | Associate transaction with this alpha-numeric user defined tag. It is normally used to associate a transaction with an affiliate or referral partner, enabling per-affiliate commission and chargeback reports within the administration system. |
dynip_sec_code | 16 | This field should be used only when a Direct Mode client is unable to connect to the server from a Trusted Static IP Address and must connect from a dynamic or unknown IP Address. Direct Mode clients are authenticated based on the Trusted Static IP Addresses configured on the account's Access Security settings page. If a connection from a dynamic or unknown IP address is required, the Dynamic IP Security Code can also be configured on the same page. If the correct Code is sent in this field, transactions will be accepted regardless of the IP. |
pay_type | 1 |
This is required for all transactions. Possible values: C (credit card) K (check) |
tran_type | 1 |
This is required for all transactions. Possible values: A - authorize funds only, no funds will be transferred S - sale, funds will be transferred Q - quasi transaction (or quiet transaction). Stores cardholder information for later use. Nothing is sent to the processor. R - refund a previous sale, a partial amount can be specified (auth-reversal is performed when possible.) C - credit funds back without referencing a previous sale. U - attempt to undo one of the above transaction types (auth-reversal is performed when possible, support varies by processor) D - capture a previous authorization, effectively converting it into a sale. B - batch settlement, all outstanding sale, refund and credit transactions are settled with the bank. |
trans_id | 12 | Transaction ID for transaction request. This field is optional. When used, the value MUST have been obtained by querying getid3.2. This field allows tracking of a transaction, even if a response is never received due to network latency, etc. If no value is supplied, the system will generate a unique ID and returned in the response message. |
orig_id | 12 | Transaction ID of the original transaction. I.e. trans_id of original Sale or Auth. |
amount | 10 | This is the total amount of the transaction, including tax and shipping, if any. No spaces, commas or currency signs. It should include all tax and shipping amounts, even if those amounts are specified separately. |
tax_amount | 10 | This is the tax amount of the transaction. Required to qualify for Purchase/Commercial Card Level-2 processing. No spaces, commas or currency signs. |
ship_amount | 10 | This is the shipping cost of the transaction. Required to qualify for Purchase/Commercial Card Level-2 processing. No spaces, commas or currency signs. |
purch_order | 17 | This is the Purchase Order number. Required to qualify for Purchase/Commercial Card Level-2 processing. |
courier_tracking | 100 | The courier designation, "FEDEX", "UPS", "USPS", "TNT", or "DHL" followed by a colon and the tracking number (no spaces.) For example: "FEDEX:844477771111". Specifying this enables the system to provide automatic links directly to the tracking information for the carrier. |
processor | 10 |
Request that the transaction is processed using the specified processor routing prefix. A processor with the same
routing prefix must be configured for the account. It can be used to ensure that transactions
for a card already billed in the past are routed through the same processor again. Useful for accounts with load sharing
between multiple processors.
In this case pass the value returned in the response parameter of a prior transaction.
Note: If an inactive or invalid routing prefix is specified, this parameter may be silently ignored. Example: "PTECH", "INT/CX" or "INT/CX#5", etc. If the optional prefix extension ("#5" in the example) is not specified and multiple INT/CX-MIDs are configured, the system will make the selection among them. |
Customer information parameters | ||
bill_name1 | 20 | First name of paying customer. |
bill_name2 | 20 | Last name of paying customer. |
bill_street | 80 | Street address of paying customer. Must match the credit card billing address, or the bank statement address for NBCheck transactions. |
bill_city | 40 | City of paying customer. |
bill_state | 30 | 2 character US state code of paying customer, or foreign state or province. Do not specify spelled out state names for US states. |
bill_zip | 20 | 5 or 9 digit US zip code or foreign postal code of paying customer. Must match the credit card billing address, or the bank statement address for NBCheck transactions. Format: "55555" or "55555-4444" for US zip codes. |
bill_country | 2 | The 2 letter ISO3166 country code of paying customer. "US" for the United States, "GB" for the United Kingdom, etc. See ISO Country Codes |
ship_name1 | 20 | First name of shipping recipient. |
ship_name2 | 20 | Last name of shipping recipient. |
ship_street | 80 | Street address of shipping recipient. |
ship_city | 40 | City of shipping recipient. |
ship_state | 30 | 2 character US state code or foreign state or province of shipping recipient. Do not specify spelled out state names for US states. |
ship_zip | 20 | 5 or 9 digit US zip code, or foreign postal code of shipping recipient. Format: "55555" or "55555-4444" for US zip codes. |
ship_country | 2 | The 2 letter ISO3166 country code of shipping recipient. "US" for the United States, "GB" for the United Kingdom, etc. See ISO Country Codes |
cust_email | 60 | Email address of the customer. Optional, but necessary for the system to send email receipts. |
cust_phone | 40 | Phone number of the customer. |
cust_ip | 15 | IP address of the customer for web originating transactions. |
cust_host | 255 | The resolved DNS host name of the customer for web originating transactions. |
cust_browser | 200 | The User-Agent customer browser header for web originating transactions. |
Purchase information parameters | ||
description | 4000 | A description or order reference for the order. |
user_data | 4000 |
Arbitrary user data that will be stored by the system. It can be used to store attribute value pairs, separated by newline (\n) characters. For example:
Customer-Number: 1234 |
misc_info | 4000 |
Arbitrary miscellaneous information that will be stored by the system. Merchants submitting NBCheck transactions must populate this field with the transaction date and the full text of the required agreement authorized by the customer at the time of the sale. |
Fraud control and special feature parameters | ||
disable_avs | 5 | Set this flag to a true value ("true", "yes" or "1") to disable AVS (Address Verification System) for this credit card transaction. |
disable_cvv2 | 5 | Set this flag to true value ("true", "yes" or "1") to disable CVV2 (Card Verification Value 2) for this credit card transaction. |
disable_fraud_checks | 5 | Set this flag to true value ("true", "yes" or "1") to disable all fraud protection other than AVS/CVV2. This implies disable_negative_db. |
disable_negative_db | 5 | Set this flag to true value ("true", "yes" or "1") to disable only the negative database component of the fraud protection system. |
disable_email_receipts | 5 | Set this flag to true value ("true", "yes" or "1") to disable automatic sending of both merchant and customer email receipts. |
disable_expiration_check | 5 | Set this flag to true value ("true", "yes" or "1") to disable immediate rejection of expired cards. |
disable_cascading | 5 | Set this flag to true value ("true", "yes" or "1") to disable cascading for a single transaction. |
partial_approval | 5 | Set this flag to true value ("true", "yes" or "1") to indicate that an authorization for a partial amount is acceptable. This is used with MC gift cards which may have insufficient balance to cover the entire purchase. The amount reserved is returned in the settle_amount response variable. If this value is less than the full amount, the consumer would be prompted to provide an additional card and a separate transaction initiated for the difference. If additional funds cannot be secured, remember to undo the partial approval! |
Credit card parameters | ||
card_number | 19 | Credit card number used for the transaction. No spaces or dashes, digits only. |
card_expire | 4 | Credit card expiration date in MMYY format (no slash). Required whenever card_number is required. |
card_cvv2 | 4 | Credit card CVV2/CVC value, which is the 3 or 4 digit code on the back of the credit card used for fraud prevention. |
card_track1 | 79 | Magnetic stripe data for track 1 used in retail environments. When sending magnetic stripe data, the card_number and card_expire fields are optional. Either track1, track2 or both can be sent. Track 1 is alpha-numeric, and will begin with '%' and end with '?'. If both tracks are available, we recommend sending track 1. |
card_track2 | 40 | Magnetic stripe data for track 2 used in retail environments. When sending magnetic stripe data, the card_number and card_expire fields are optional. Either track1, track2 or both can be sent. Track 2 is numeric, and will begin with ';' and end with '?'. |
card_start_date | 4 | Start or issue date of card in MMYY format. Like the expiration date, but indicates the beginning of the card's validity period. Used with some SoloTM/SwitchTM cards. |
card_issue_number | 2 | Card issue number. Some SoloTM/SwitchTM issuing banks use this number, others use a start date (above) instead. |
force_code | 15 | Authorization force code (usually 6 digits), typically obtained by phone authorization. This code is used to force a through a sale that would otherwise fail with a CALL CENTER message. |
3ds_eci | 4 | Electronic Commerce Indicator. Required if provided by the 3D Secure MPI (Merchant Plug-In). Up to 4 characters. Normally 1 or 2 digits. |
3ds_cavv | 64 | Required when using Verified by VisaTM (also known as 3D Secure.) MC refers to this value as UCAF. Up to 64 hexadecimal digits in ASCII, encoding up to 32 bytes of binary data, or up to 44 characters of Base64 code. This value is provided by the MPI (Merchant Plug-In). |
3ds_xid | 40 | Required if provided by the 3D Secure MPI (Merchant Plug-In). Format: 40 hexadecimal digits in ASCII, encoding a 20 byte binary value, or 28 characters of Base64 code. If the 3DS_version parameter is provided with the value of "2", this is where the "Directory Server Trans ID" typically provided by the MPI as a 32 or 36 digit UUID would be submitted. |
3ds_version | 1 | This parameter is optional. The value for this parameter should be 2 or 1. If this parameter is omitted, the version is assumed to be 1. |
enable_3ds_mpi | 5 | Case-insensitive. Send a true value ("true", "yes", "both" or "1") to enable the built-in 3DSecure 2 MPI. The gateway will assist you in collecting the values needed for cavv and xid. Set this to "mc" or "visa" to enable the mpi only for one specific card network. This parameter is ignored if there is any data submitted in 3ds_eci, 3ds_cavv, or 3ds_xid. |
3ds_return_url | - | This parameter is only necessary when using the built-in 3DSecure 2 MPI. Set this parameter to a URL hosted by the merchant. This URL will receive 3DS challenge completion messages in a parameter named cres. |
3ds_cres | - | This parameter is only necessary when using the built-in 3DSecure 2 MPI. This should contain the cres parameter you received in the Challenge Response, copied exactly as-is. |
3ds_mid | - | This parameter is only necessary when using the built-in 3DSecure 2 MPI. Used to identify yourself to the 3DS2 network. If you're unsure what to put here, please contact support. |
3ds_currency | - | The ISO 4217 numeric currency code. This parameter is only necessary when using the built-in 3DSecure 2 MPI. Example value: 840. |
NBCheck parameters | ||
account_number | 27 | Checking account number in <aba>:<account_no> format, e.g. "123456789:9999999999" where 123456789 is the bank's 9 digit ABA (routing) number, and 9999999999 is the checking account number (both are printed at the bottom of all checks) |
bill_photo_id_no | 20 | Paying customer's state issued drivers license or photo ID number. Typically only used for check payments. Valid characters are '0'-'9', 'A'-'Z' and '*' (used in WA-state.) Dashes and spaces should not be included. |
bill_photo_id_state | 2 | Paying customer's 2 letter state code for the state that issued the photo id above. if the photo id is federal, this field should be "US". Typically only used for check payments. |
bill_tax_id_no | 12 | Paying customer's Tax ID or Social Security number. Format: 333-22-4444 for SS#, 22-7777777 for TID#. Typically only used for check payments. |
bill_birth_date | 17 | Paying customer's birth date in YYYY-MM-DD format. Typically only used for check payments. |
assent_key | 16 | This is a unique numeric key required by the system to verify that a customer has agreed to the NBCheck Terms Of Service. The merchant checkout page must include a specific <img> tag and JavaScript code which cause the assent_key to be linked with the customer's agreement to the Terms Of Service language contained in the image. Please review the assent_key documentation which include an example of how to use this feature. For merchant initiated repeat billing of the same customer, the assent_key value from the original transaction should be included. The customer must have agreed to repeat/recurring billing at the time of the original transaction. Future repeat billing of transactions that were originally processed before the assent_key feature was introduced are grand-fathered, and will continue to be approved without it. All new ACH transactions require a valid assent_key. |
Hotel industry parameters | ||
hotel_checkin_date | 6 | Actual or anticipated checkin date YYMMDD format for hotel industry transactions. |
hotel_checkout_date | 6 | Actual or anticipated checkout date YYMMDD format for hotel industry transactions. |
hotel_flags | 10 |
This field contains a string of one or more single-letter flags pertaining to the transaction:
None, One or Several of the following flags can be specified
None or One of the following flags can be specified When specifying multiple flags, simply append them together without spaces. The order is not important. |
hotel_room_rate | 10 | The daily room rate. No spaces, commas or currency signs. |
mcc_override | 4 |
4 digit MCC (Merchant Category Code) override. Can be used to
indicate that a specific transaction was not a hotel-industry transaction,
even thought the account is setup for hotel processing by default.
This field is used to indicate the appropriate industry code for a separate restaurant. gift shop or other purchase, that is not processed together with hotel charges. |
Membership and Recurring Billing | ||
member_id | 12 |
This optional parameter can be used in two situations:
(1) A new member is being created (member_username must be specified) and you want to assign a specific ID to the member. The ID, if specified, MUST have been obtained by querying getid3.2. (2) A member is not being created (member_username is not specified) but you want to link this transaction to a previously known member ID. This is commonly done for reporting purposes or to "upsell" additional site tags to an existing member. |
disable_member_upjoin | 5 | This optional parameter only applies when member_id is specified for an existing member ID (situation 2 above.) By default, any site tag(s) specified in site_tag will be added to the member's subscription profile if the transaction succeeds. A true value ("true", "yes" or "1") prevents changes to site memberships. |
member_username | 60 | Name of the subscribing member. This is the name that will be used by the member to login to the subscription site. It must be unique with respect to other members of the same site_tag. If a name is already in use, the request will fail and no transaction will be processed. |
member_duration | 6 | The duration in days of the initial membership. |
member_password | 60 | The password the member will use to login to the subscription site. |
member_memo | 4000 | An optional merchant memo to attach to this member. |
recurring_amount | 10 | The amount to bill the subscriber for at the end of the initial membership. If a recurring billing is successful, the subscriber's expiration date is automatically pushed forward until the time of the next recurring billing. |
recurring_period | 100 | The time period between subsequent recurring billings. This is specified either as a number of days, or a special expression as generated by the Button Editor in the Online Administration can be used. |
recurring_count | 10 | Stop the recurring billing after this number of successful recurring billings have been processed. The default is no limit. |
recurring_prorate | 4 |
When set to "true", the next recurring billing will occur either at the end of the initial
membership period (member_duration), or at the next matching recurring_period special expression,
whichever is sooner. The amount of the first recurring billing will be be reduced based on
how many days early the recurring billing occurred compared to the number of days specified in
member_duration.
Example: member_duration=30 & recurring_period=last_day%28sysdate%29%2B1 & recurring_prorate=true This recurring_period expression specifies that this subscriber should be billed on the 1st of every month. If the subscriber joined on the 18th of February, the first recurring billing would occur on the 1st of March. The amount would be reduced by 2/3rd of the initial transaction amount, because the initial payment was for a 30 day membership, but the first recurring billing was processed after only 10 days, thus a credit is given for 20 days. From then on, the subscriber will always be billed the amount specified in recurring_amount on the 1st of each month. |
IMPORTANT NOTE: Properly implemented client software --
Transaction Response Parameter Definition Table | |
---|---|
status_code |
Single character status code.
1 - Successful monetary transaction Any unexpected status code other than "0" and "F" should be interpreted as a successful transaction. |
trans_id | If trans_id was supplied in the request, the same code will be returned (except for Duplicate transaction errors.) If trans_id was not supplied in the request, a unique system generated ID will be returned. |
auth_code | A 6 digit (alphanumeric) authorization code generated by the bank. |
auth_date | This is the date and time in GMT (UTC) when the transaction was authorized by the system. "YYYY-MM-DD HH:MM:SS" format. |
auth_msg | A human readable approval message, for example "APPROVED 123456", or "DECLINED 05". These messages are processor specific, may change, and are not intended to be machine readable. |
avs_code | Single character AVS result code. See the AVS popup window in the online administration system for a list of codes. |
cvv2_code | Single character CVV2 result code. See the CVV2 popup window in the online administration system for a list of codes. |
ticket_code | Typically not used. Processor specific additional transaction reference code. |
reason_code2 | Typically not used. Processor specific additional DECLINE-reason code. Consult the transaction details screen for a declined transaction in the online administration system for verbose reason code messages. |
member_id | Returned when a new subscriber/member was added. |
recurring_id | Returned when a recurring billing record was established for a new subscriber/member. |
settle_amount | The settlement amount. The same as the request amount, except for Dynamic Currency Conversion merchants, where this field together with settle_currency indicate the actual amount and currency billed to the cardholder. It may also be less than the requested amount in case of partial authorizations for MasterCard gift cards, in which case merchants would initiate a 2nd transaction using a different card for the remaining amount and/or cancel the partial approval. See partial_approval. |
settle_currency | The settlement currency, typically "USD". For Dynamic Currency Conversion merchants, this field together with settle_amount indicate the actual amount and currency billed to the cardholder. |
processor | The processor routing prefix used to process transaction. This is useful primarily for load-balanced multi-processor accounts. If a specific processor was requested using the input parameter, this can be used as positive confirmation. |
card_flags | Will be P when the card has been identified as a prepaid card. Not included in response otherwise. |
3ds_url |
Only returned if enable_3ds_mpi was true. You must redirect the customer to this URL so they can type in their security information. This is the URL of the 3rd party ACS (Access Control Server). The ACS contains the authentication rules and is controlled by the Card Issuer. Thus, the URL can change from card to card. The redirect must be a POST. Set the Content_Type header of the POST to application/x-www-form-urlencoded. The payload of the POST must contain a creq parameter. Set the creq parameter to the string you received in 3ds_creq. |
3ds_creq |
Only returned if enable_3ds_mpi was true. This is the creq parameter that you are required to send to the ACS in the body of the POST. You don't need to decode it, just pass it along as-is. |
Settlement Response Parameter Definition Table | |
---|---|
STATUS |
Single character batch settlement status code.
1 - (one) Successful batch settlement Any unexpected status code other than "0" and "O" should be interpreted as a successful settlement. |
PAY_TYPE | Single character pay_type, echoed from request. |
ID | System ID number uniquely identifying the batch settlement record. |
REPORT_DATE | This is the date and time in GMT (UTC) when the batch settlement was performed. "YYYY-MM-DD HH:MM:SS" format. |
CLOSE_BALANCE | The settlement balance. Positive for net deposits, negative if there are more refunds than sales in the batch. |
CLOSE_MSG | A human readable settlement message, for example "BATCH SETTLED". These messages are processor specific, may change, and are not intended to be machine readable. |
Codes 699 and 799 are general codes returned for many different reasons. If you need to do special processing for one of those codes, your application also needs to look at the first 5 digits of the HTTP message in order to match a particular error.
Exception code ranges | |
---|---|
600 - 698 | Exception is most likely due to invalid input. The HTTP message contains a human-readable error message. |
700 - 798 | Exception is most likely due to processing error. The HTTP message contains a human-readable error message. |
699, 799 | The HTTP message will begin with an addition 5 digit machine-readable code that is used to further
narrow down the error in software exception handling. For example:
HTTP/1.0 699 20112: Invalid card expiration date 0x09
Connection: close Content-Type: text/plain Content-Length: 0 In this example, 20112 indicates that an invalid card expiration date was given. |
NOTE: You should never send a "home made" trans_id or member_id. When using those fields, all id numbers must be obtained using the getid3.2 method.
ID numbers are obtained by a GET or POST request to http://secure.netbilling.com:1401/gw/sas/getid3.2. For high speed applications that wish to take advantage of ID number caching, up to 10 IDs can be requested simultaneously, by passing a number (1-10) in the body of a POST, or in the query string of a GET request. e.g. http://secure.netbilling.com:1401/gw/sas/getid3.2?3.
The ID numbers are returned in the body of the text/plain response. Multiple IDs are separated by new-line characters.
The system supports PCI compliant cardholder data storage, which can be used to perform Repeat Billing, up-selling and cross-selling at a later time for a previous customer, without requiring the storage of cardholder data at the merchant site.
The PCI security standards are technical and operational requirements that were created to help organizations that process card payments prevent credit card fraud, hacking and various other security vulnerabilities and threats. The standards apply to all organizations that store, process or transmit cardholder data. A company processing, storing, or transmitting cardholder data must be PCI DSS compliant.
To take advantage of this feature, PCI storage must be enabled in Step 6 of the Credit Card setup page.
To change any of the stored information, such as the billing address, the updated information can be specified when issuing a Repeat Billing, up-sell or cross-sell, and it will override the previously stored information. The new trans_id for the updated transaction can be used in the future to perform another Repeat Billing, up-sell or cross-sell using the updated default information.
Repeat Billing and Up-selling
This feature enables you to perform a future repeat-billing or up-sell for the same consumer within the same gateway account, rather than storing and specifying the card number and billing address again. Simply check "Enable PCI Compliant Repeat Billing, Up-selling and Cross-selling" in Step 6 of the Credit Cards setup page. When the feature is enabled, you would send "CS:123456789012" as the card_number, where 123456789012 is the trans_id of the original transaction.
Note: If the new transaction is to be processed through a different gateway account than the original sale, it's considered cross-selling. See below.
Cross-sellingTo allow cross-selling without an affiliate having to know the card number or billing information, simply specify a space-separated list of affiliate accounts authorized to use this feature under Authorized affiliate accounts in Step 6 of the Credit Card setup page. The affiliate must send "CS:123456789012:4444" as the card_number, where 123456789012 is the trans_id of the original transaction, and 4444 is the last 4 digits of the card number. The ":4444" is required to confirm the card number. The merchant must share each appropriate "CS:" original transaction ID and the last four digits of the card number with the affiliate, in accordance with their mutual agreement.
For example, a merchant may have a checkbox on its payment form for a special offer from one of its affiliates. If a customer selects to take advantage of this offer, after completing the transaction, the merchant will send the "CS:" transaction id to the affiliate. The affiliate will then proceed to bill the customer for the sale and ship the product.
Note: MasterCard no longer permits cross-selling. Any affiliate that you choose to prevent from running MasterCard transactions should be listed under Authorized affiliate accounts.
Membership and recurring billing records can be automatically managed by the system, including PCI compliant storage of cardholder data. While these features are primarily intended to automate much of the management for developers of member-based websites, this feature can be used by any merchants that are interested in setting up some form of automated billing for their customers.
All recurring billing records that will be setup for automatic management must be created in association with a membership. The setup of such recurring billing records can be accomplished by including the "site_tag" parameter as well as all relevant and required "Membership and Recurring Billing" fields with the transaction request (as outlined in section 2.2 of this document). If this option is used all information relating to the membership and the associated recurring billing setup will be stored and processed automatically by the system. For member based websites the system can also manage the login and password information automatically by sending information to a control CGI on your web-server. The specifics of the CGI Membership postings are covered in detail in separate documentation.
Recurring billing setup through Direct Mode can be used to automatically re-bill the customer's credit card to renew the membership on a regular basis. Recurring billing periods can be specified as either a number of days between recurring billing attempts (ex. 1, 7, 30) or as a special period expression. If specified as a special period expression the initial membership period can also be prorated. This allows membership sign-ups to take place at any time during the month but automatically scale the charge amount to match the possible reduced period of time until the first scheduled recurring billing.
Please note that a membership can be associated with multiple site tags by including a comma separated list of site tags as the value for the "site_tag" field instead of just a single tag. The first site tag in this list will become the member's primary site while the others will be automatically set as additional sites that membership has been granted access to.
If you are using a 3rd party MPI (Merchant Plugin) to authenticate transactions with 3DSecure 2, include the values returned by the MPI to the transaction in the parameters 3ds_eci, 3ds_cavv, and 3ds_xid. For example:
If you do not have an MPI but instead wish the gateway to perform the 3DSecure 2 authentication, send the enable_3ds_mpi, 3ds_mid, 3ds_currency, and 3ds_return_url parameters. For example:
At this point, the customer may or may not be required to answer a 3DSecure Challenge. There are many reasons why a 3DS Challenge may not be required. The card may not be enrolled in 3DS; The card may be enrolled but the transaction qualifies for frictionless 3DS authentication; or, some kind of error occurs. If a 3DS Challenge is not required, then the transaction processes normally, a typical Direct Mode response is returned, and there are no further steps to take. The transaction is complete.
If a 3DS Challenge is determined to be necessary, then the transaction is not sent to the processor but rather stored locally as if you had sent a tran_type=Q transaction. The Direct Mode response will contain the trans_id of the stored transaction as well as the 3ds_url and 3ds_creq parameters. For example:
You must redirect the customer to the URL you received in 3ds_url so they can type in their security information. This is the URL of the 3rd party ACS (Access Control Server). The ACS contains the authentication rules and is controlled by the Card Issuer. Thus, the URL can change from card to card. The redirect must be a POST. Set the Content_Type header of the POST to application/x-www-form-urlencoded. The payload of the POST must contain a creq parameter. Set the creq parameter to the string you received in 3ds_creq.
In addition to creq, you will most likely want to include a threeDSSessionData parameter. If included, this parameter must be Base64URL encoded without padding. This parameter can help tie challenge completion messages (CRes messages) back to their originating transactions so they can be submitted back to Direct Mode for payment processing. For example, you might encode the trans_id you received, 210742956290, as MjEwNzQyOTU2Mjkw.
To continue the previous example, you might request the customer's browser to sumbit the following POST:
The customer's browser will now be displaying a challenge webpage hosted by the ACS. The customer will be asked to type in security information. For example, they may be asked to type in a code that was texted to their phone. When the challenge is successfully completed, the ACS will send an HTTP POST to the URL you provided in 3ds_return_url. For example, you might receive the following POST from the ACS:
You would now forward this cres parameter in a new request to Direct Mode to complete the payment transaction, using 3ds_cres. Since the transaction is already stored in the gateway, it isn't necessary to submit all of the information again. Continuing with the example, threeDSSessionData=MjEwNzQyOTU2Mjkw decodes into 210742956290. That will be used to reference the transaction stored on the gateway, using the orig_id parameter. Set tran_type D to indicate you're authing and capturing an existing transaction. If the processor requires CVV2, you'll need to send that in the card_cvv2 parameter since it cannot be stored. One method of preserving the cvv2 would be to encode it into the threeDSSessionData parameter. Here is what you might post to the gateway:
When Direct Mode receives this request, it will obtain the cavv/xid from the 3DSecure network using the cres provided, then forward the transaction to the processor with cavv/xid included. Payment processing will complete as normal and a typical Direct Mode response will be returned.