Netswipe Processing Implementation

(1)

Netswipe Processing Implementation

Direct Integration with Jumio’s Payment Gateway

Revision History

Version Date published Description

1.0.0 November 22nd

, 2011 Initial release.

1.0.1 January 12th

, 2012 Added basic authentication

1.0.2 July 19th_{, 2012} _{Changed credentials for basic authentication} 1.0.3 October 25th, 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 ... 7 Parameter ... 7 Return values ... 8 Capture ... 8 Parameter ... 8 Return values ... 8 Void ... 8 Parameter ... 8 Return values ... 8 Payment ... 9 Parameter ... 9 Return values ... 9 Refund ... 10 Parameter ... 10 Return values ... 10 Referral Approval ... 10 Parameter ... 10 Return values ... 11 Credit ... 11 Parameter ... 11 Return values ... 12

(3)

Card Fund Transfer ... 12 Parameter ... 12 Return values ... 13 Recurring Operations ... 14 Register Card ... 14 Parameter ... 14 Return values ... 14 Authorize ... 14 Parameter ... 14 Return values ... 15 Payment ... 15 Parameter ... 15 Return values ... 15 Credit ... 16 Parameter ... 16 Return values ... 16

Card Fund Transfer ... 16

Parameter ... 16

Return values ... 17

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

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 https://processing.jumio.com/api/pay/v1/basicoperations/authorize Accept: application/json Content-Type: application/json Authorization: Basic { "country":"USA", "amount":"10.99", "currency":"USD", "cardNumber":"1234123412341234", "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 www.jumio.com 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.

https://processing.jumio.com/api/pay/v1/basicoperations/authorize

Parameter

Name Type Required Description

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

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)

Return values

Name Type Description

result Integer Returncode

response String Returnmessage

jumioPaymentReference String Guid returned from Operation jumioCardReference String Guid of used credit card timestamp DateTime Timestamp of Operation

Capture

This is for collecting money from the customer . An authorize operation must be done before. Only one Capture can be done per Authorization.

https://processing.jumio.com/api/pay/v1/ basicoperations /capture

Parameter

jumioPaymentReference String Yes Guid obtained with an Authorize transaction.

Return values

Void

This is for closing a transaction previously opened by an Authorization-operation without collecting money.

https://processing.jumio.com/api/pay/v1/basicoperations/void

Parameter

jumioPaymentReference String Yes Guid obtained with an Authorize transaction

Return values

(9)

Payment

This is a one-step operation for collecting money from the customer.

https://processing.jumio.com/api/pay/v1/basicoperations/payment

Parameter

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

Return values

(10)

Refund

This is for returning money from a previously done transaction to the customer.

https://processing.jumio.com/api/pay/v1/basicoperations/refund

Parameter

jumioPaymentReference String Yes Guid obtained with a Payment or Capture transaction.

Return values

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.

https://processing.jumio.com/api/pay/v1/basicoperations/referralapproval

Parameter

jumioPaymentReference String Yes Guid obtained with an Authorize or Payment transaction.

approvalCode String Yes Approval code obtained calling the Authorization Center.

(11)

Return values

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.

https://processing.jumio.com/api/pay/v1/basicoperations/credit

Parameter

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)

Return values

Card Fund Transfer

This is limited to gambling accounts. Please get in touch for further information.

https://processing.jumio.com/api/pay/v1/basicoperations/cardfundtransfer

Parameter

(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

Return values

(14)

Recurring Operations

Register Card

This method allows you to register credit cards in the system to be used later.

https://processing.jumio.com/api/pay/v1/recurringoperations/registercard

Parameter

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.

Return values

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

https://processing.jumio.com/api/pay/v1/recurringoperations/authorize

Parameter

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

Return values

Payment

https://processing.jumio.com/api/pay/v1/recurringoperations/payment

Parameter

Return values

(16)

Credit

https://processing.jumio.com/api/pay/v1/recurringoperations/credit

Parameter

Return values

Card Fund Transfer

http://processing.jumio.com/api/pay/v1/recurringoperations/cardfundtransfer

Parameter

(17)

Return values

(18)

Appendix

Result code

Code Description

0 OK There were no errors during the execution of the operation

1000 ParameterError This code groups all errors related to the parameters sent. 2000 PaymentGatewayError Groups all errors related to paymentgateway 3000 Declined Groups all responses related to declines

3100 ReferralTransactionError Groups all responses related to Referral transactions. 3200 AcquiringBankError all errors related to the acquiring bank

4000 SecurityError all errors regarding security issues. 5000 UnexpectedError Groups all unexpected errors

6000

BusinessRuleError Groups all codes different than 0 given by the business rules 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.