Netswipe Processing Implementation

Transcription

1 Netswipe Processing Implementation Direct Integration with Jumio s Payment Gateway Revision History Version Date published Description November 22 nd, 2011 Initial release January 12 th, 2012 Added basic authentication July 19 th, 2012 Changed credentials for basic authentication October 25 th, 2012 Added sample request

2 Netswipe Processing Implementation... 1 Authorize... 4 Capture... 4 Void... 4 Payment... 4 Refund... 5 Credit... 5 Card Fund Transfer... 5 Referral Approval... 5 General settings... 6 JSON request... 6 Basic Authentication... 6 Basic Operations... 7 Authorize Capture Void Payment Refund Referral Approval Credit

3 Card Fund Transfer Recurring Operations Register Card Authorize Payment Credit Card Fund Transfer Appendix Result code... 18

4 This section provides a functional overview of the operations that Jumio supports for processing card transactions: Authorize Capture Void Payment Refund Credit Card Fund Transfer Referral Approval Authorize The authorize operation allows the merchant to book the desired money from the card that will be invoiced. This is the preferred method since it provides the bank authorization to collect the money from the customer, but without collect immediately. This operation has two-steps and must always be completed by voiding the transaction or capturing, the completion can be done within an average time of 20 days. If the capture is not performed, the system will purge authorizations older than 20 days. This means that you will not be able to capture authorizations after they are purged. If you don t execute a Void operation, the money of purged authorizations will be blocked for the card until the issuing bank releases it. To avoid that, always call the Void method. Capture The Capture operation consists of collecting the money from authorizations previously done. Normally a Capture is performed for the total amount of the transaction, however, it might be possible to capture only part of the money reserved. Note: Only one Capture operation can be performed per Authorization. Void The Void operation is used to avoid collecting the money from authorizations previously done. This releases the money blocked from the credit card without collecting it. The Void can only be performed for the total amount of the Authorization, if exists a Capture or Partial Capture the Void operation will not be performed. Payment This is the easiest way to bill an amount over a card. The Payment operation collects the amount desired immediately. This is the equivalent of doing both an authorization and a capture at once.

5 Refund The Refund operation, as its name states, consists of returning money already collected by a Payment or a Capture transaction. The amount collected can be refunded in total or partially. You cannot refund amounts larger than the one sent in the original transaction. Refund can only be performed if a customer has not initiated a chargeback procedure. Note: You can perform multiple refunds until you reach the total amount of the original Payment or Capture. Credit The Credit operation allows refunding to the card holder. The main difference with a Refund operation is that it is a stand-alone operation. That means a Credit does not need to match a prior Payment or Capture. NOTE: This operation is disabled by default. You need you own payment gateway account when you want to use credit operation. Please contact [email protected] for more details. Card Fund Transfer The card fund transfer is the ability to transfer money from a merchant account to a cardholder account and is limited to 7995 coded (gambling) accounts. The amount that can be transferred is not limited by the amount collected in the first place. NOTE: This operation can only be used to transfer money to cards that have been already used to perform a Capture or Payment in the same merchant account. NOTE: This operation is disabled by default. You need you own payment gateway account when you want to use credit operation. Please contact [email protected] for more details. Referral Approval During an Authorize or Payment it is possible that a transaction is not declined nor approved. In this case you will get a Referral. The most common case for this error includes large transactions. When a Referral occurs the bank requires an extra authorization via telephone as an additional security measure. The procedure to follow in order to get your transaction approved consists of calling the Authorization Center and obtaining an Approval Code, after which you will need to perform a ReferralApproval request to Jumio.

6 General settings JSON request Jumio offers a payment API for merchants needing a RESTful solution for credict card processing without a Jumio hosted user interface. All you have to do is send a HTTP POST to the URLs mentioned below with JSON parameters. Note: Set "accept: application/json" and "content-type: application/json" in the "header" section of your request. Sample request: POST Accept: application/json Content-Type: application/json Authorization: Basic { "country":"usa", "amount":"10.99", "currency":"usd", "cardnumber":" ", "cardexpirymonth":"1", "cardexpiryyear":"2015", "cardcvv":"123" } Basic Authentication Every processing API call is protected. Please use HTTP Basic Authentication, with your Jumio merchant API token as "userid" and your API secret as "password." The merchant API token can be found at the bottom of each page on after you are logged in. The API secret is provided on the Settings page under Change Credentials.

7 Basic Operations Authorize This operation allows the merchant to book money from the card that will be invoiced. This is the preferred method since it provides the bank authorization to collect the money from the customer, but without collect it immediately. It is a two-step operation which must be completed by either a capture or a void operation. country String Yes ISO 3166 Country code that indicates from which country comes the transaction (e.g. AUT, USA, ) amount Decimal Yes Transaction amount. The decimal separator must be a point. currency String Yes ISO 4217 Currency code that indicates the currency of the transaction (e.g. EUR, USD, ) cardnumber String Yes Card holder account number. cardholder String No Card holder name as it appears in the card. cardexpirymonth Int Yes Card expiration Month. Valid values are from 1 to 12. cardexpiryyear Int Yes Card expiration Year expressed with 4 digits. i.e cardcvv String No Card validation code. Each card type has a unique name for this field. Visa (Cvv2), Mastercard (Cvc2), Amex (CID) This field is optional depending on the merchant account type. Moto and Recurring transactions don t require it. dynamicdescriptor String No Please ask for more information avsaddress String No Street address for AVS verification. avszip String No Zip Code for AVS verification. merchantpaymentreference String No This is a merchant definable value which will be shown a reference in payment portal

8 Capture This is for collecting money from the customer. An authorize operation must be done before. Only one Capture can be done per Authorization. basicoperations /capture jumiopaymentreference String Yes Guid obtained with an Authorize transaction. Void This is for closing a transaction previously opened by an Authorization-operation without collecting money. jumiopaymentreference String Yes Guid obtained with an Authorize transaction

9 Payment This is a one-step operation for collecting money from the customer. country String Yes ISO 3166 Country code that indicates from which country comes the transaction (e.g. AUT, USA, ) amount Decimal Yes Transaction amount. The decimal separator must be a point. currency String Yes ISO 4217 Currency code that indicates the currency of the transaction (e.g. EUR, USD, ) cardnumber String Yes Card holder account number. cardholder String No Card holder name as it appears in the card. cardexpirymonth Int Yes Card expiration Month. Valid values are from 1 to 12. cardexpiryyear Int Yes Card expiration Year expressed with 4 digits. i.e cardcvv String No Card validation code. Each card type has a unique name for this field. Visa (Cvv2), Mastercard (Cvc2), Amex (CID) This field is optional depending on the merchant account type. Moto and Recurring transactions don t require this field. dynamicdescriptor String No Please ask for more information avsaddress String No Street address for AVS verification avszip String No Zip Code for AVS verification. merchantpaymentreference String No This is a merchant definable value which will be shown a reference in payment portal

10 Refund This is for returning money from a previously done transaction to the customer. jumiopaymentreference String Yes Guid obtained with a Payment or Capture transaction. Referral Approval During an Authorize or Payment it s possible that a transaction is not declined nor approved, but you get a Referral. The most common case for this error includes large transactions. When a Referral occurs the bank requires an extra authorization via telephone as an additional security measure. The procedure to follow in order to get your transaction approved, consists of calling the Authorization Center and obtaining an Approval Code, after which you will need to perform a ReferralApproval request. jumiopaymentreference String Yes Guid obtained with an Authorize or Payment transaction. approvalcode String Yes Approval code obtained calling the Authorization Center.

11 Credit This is a one-step operation for refunding without previously done Payment or Capture. NOTE: This operation is disabled by default. You need you own payment gateway account when you want to use credit operation. Please contact [email protected] for more details. country String Yes ISO 3166 Country code that indicates from which country comes the transaction (e.g. AUT, USA, ) amount Decimal Yes Transaction amount. The decimal separator must be a point. currency String Yes ISO 4217 Currency code that indicates the currency of the transaction (e.g. EUR, USD, ) cardnumber String Yes Card holder account number. cardholder String No Card holder name as it appears in the card. cardexpirymonth Int Yes Card expiration Month. Valid values are from 1 to 12. cardexpiryyear Int Yes Card expiration Year expressed with 4 digits. i.e cardcvv String No Card validation code. Each card type has a unique name for this field. Visa (Cvv2), Mastercard (Cvc2), Amex (CID) This field is optional depending on the merchant account type. Moto and Recurring transactions don t require this field. dynamicdescriptor String No Please ask for more information avsaddress String No Street address for AVS verification. avszip String No Zip Code for AVS verification. merchantpaymentreference String No This is a merchant definable value

12 which will be shown a reference in payment portal Card Fund Transfer This is limited to gambling accounts. Please get in touch for further information. NOTE: This operation is disabled by default. You need you own payment gateway account when you want to use credit operation. Please contact [email protected] for more details. country String Yes ISO 3166 Country code that indicates from which country comes the transaction (e.g. AUT, USA, ) amount Decimal Yes Transaction amount. The decimal separator must be a point. currency String Yes ISO 4217 Currency code that indicates the currency of the transaction (e.g. EUR, USD, ) cardnumber String Yes Card holder account number. cardholder String No Card holder name as it appears in the card. cardexpirymonth Int Yes Card expiration Month. Valid values are from 1 to 12. cardexpiryyear Int Yes Card expiration Year expressed with 4 digits. i.e cardcvv String No Card validation code. Each card type has a unique name for this field. Visa (Cvv2), Mastercard (Cvc2), Amex (CID) This field is optional depending on the merchant account type. Moto and Recurring transactions don t require this field. dynamicdescriptor String No Please ask for more information

13 avsaddress String No Street address for AVS verification. avszip String No Zip Code for AVS verification. merchantpaymentreference String No This is a merchant definable value which will be shown a reference in payment portal

14 Recurring Operations Register Card This method allows you to register credit cards in the system to be used later. cardnumber String Yes Card holder account number. cardholder String Yes Card holder name as it appears in the card. cardexpirymonth Int Yes Card expiration Month. Valid values are from 1 to 12. cardexpiryyear Int Yes Card expiration Year expressed with 4 digits. i.e result Integer This value indicates if the card was successfully registered or not. A 0 means Ok, different than 0 means error. response String Friendly message indicating the result of the card registration jumiocardreference Guid GUID of the card to be used on Authorize and Payment operations. Authorize country String Yes ISO 3166 Country code that indicates from which country comes the transaction (e.g. AUT, USA, ) currency String Yes ISO 4217 Currency code that indicates the currency of the transaction (e.g. EUR, USD, ) amount Decimal Yes Transaction amount. The decimal separator must be a point. jumiocardreference String Yes Card Guid obtained previously. dynamicdescriptor String No Check the Appendix of your acquirer, provided separately, to know how to format this parameter.

15 merchantpaymentreference String No This is a merchant definable value which will be shown a reference in payment portal Payment country String Yes ISO 3166 Country code that indicates from which country comes the transaction (e.g. AUT, USA, ) currency String Yes ISO 4217 Currency code that indicates the currency of the transaction (e.g. EUR, USD, ) amount Decimal Yes Transaction amount. The decimal separator must be a point. jumiocardreference String Yes Card Guid obtained previously. dynamicdescriptor String No Check the Appendix of your acquirer, provided separately, to know how to format this parameter. merchantpaymentreference String No This is a merchant definable value which will be shown a reference in payment portal

16 Credit NOTE: This operation is disabled by default. You need you own payment gateway account when you want to use credit operation. Please contact for more details. country String Yes ISO 3166 Country code that indicates from which country comes the transaction (e.g. AUT, USA, ) currency String Yes ISO 4217 Currency code that indicates the currency of the transaction (e.g. EUR, USD, ) amount Decimal Yes Transaction amount. The decimal separator must be a point. jumiocardreference String Yes Card Guid obtained previously. dynamicdescriptor String No Check the Appendix of your acquirer, provided separately, to know how to format this parameter. merchantpaymentreference String No This is a merchant definable value which will be shown a reference in payment portal Card Fund Transfer NOTE: This operation is disabled by default. You need you own payment gateway account when you want to use credit operation. Please contact [email protected] for more details. country String Yes ISO 3166 Country code that indicates from which country comes the transaction (e.g. AUT, USA, )

17 currency String Yes ISO 4217 Currency code that indicates the currency of the transaction (e.g. EUR, USD, ) amount Decimal Yes Transaction amount. The decimal separator must be a point. jumiocardreference String Yes Card Guid obtained previously. dynamicdescriptor String No Check the Appendix of your acquirer, provided separately, to know how to format this parameter. merchantpaymentreference String No This is a merchant definable value which will be shown a reference in payment portal

18 Appendix Result code Code Description 0 OK There were no errors during the execution of the operation 1000 Error This code groups all errors related to the parameters sent PaymentGatewayError Groups all errors related to paymentgateway 3000 Declined Groups all responses related to declines 3100 ReferralTransactionError Groups all responses related to Referral transactions AcquiringBankError all errors related to the acquiring bank 4000 SecurityError all errors regarding security issues UnexpectedError Groups all unexpected errors BusinessRuleError Groups all codes different than 0 given by the business rules 6000 applied to the execution of an operation. i.e. A rule preventing the execution of a Refund because a manual refund is required will produce an operation returning Result = 6000.