Accept Payments with SDK | Worldline NAM

All payment requests are made via server-side requests. You can either call our RESTful Payments API directly, or via one of our API wrapping libraries (our SDKs).

Our RESTful APIs allow you to take payments, analyze payments, create payment profile to record customer details for future payments, and create credit card tokens to reduce the scope of your PCI compliance. You can read the API Spec here .

Include the Server SDK

Select the programming language of your project from the tabs at the top-right corner of the code snippet.

Copy

// Maven


snapshots-repo
https://oss.sonatype.org/content/repositories/snapshots
false
true





com.beanstream.api
beanstream
1.0.0-SNAPSHOT



//Gradle
repositories {
    maven { url "https://oss.sonatype.org/content/repositories/snapshots" }
}
dependencies {
    compile("com.beanstream.api:beanstream:1.0.0-SNAPSHOT") {changing=true}
}

//Nuget
Id: Bambora.NA.SDK

PM> Install-Package Bambora.NA.SDK

// Composer
// 1. Edit composer.json
{
    "require": {
        "beanstream/beanstream": "dev-master"
    }
}
// 2. Install the SDK
composer install

// 3. Require in your php file
require 'vendor/autoload.php';

// Pip
pip install beanstream

Purchases and pre-auth's

A payment processes the credit card right away. A pre-authorization (aka “pre-auth”) checks to see if the customer has the funds available without actually charging them. After a pre-auth you will want to “complete” the payment for less than or equal to the original pre-auth amount.

Set the Credit Card object’s “complete” value to true to complete a payment after a pre-auth, or to just push the payment through in the first place without pre-auth.

Credit card

Test Cards
If you are using a test account, or a production account that is still in its initial 'test' mode, you’ll need to use test card numbers. You’ll be able to view the transaction process from beginning to end without sending real information to the banking network. See here for a list of test card numbers.

Required Parameters
Please refer to the API Spec for full details on parameters.

Approved and declined responses
If you are using an SDK an approved payment will return a payment response object. A declined payment will throw an exception or return an error. If you are using the REST API directly then an approved payment will return a 200 OK http status response as well as a response object.

You can view the data model of the response below in the REST API section. The data model there is the same in the REST response as well as the SDKs.

The response objects will contain all of the relevant payment information as well as a transaction ID.

For a regular credit card payment, set "complete" to "true"
For a pre-authorization, set "complete" to "false"
For a pre-authorization completion, set "complete" to "true"

Copy

# Definition
# POST /v1/payments HTTP/1.1

curl https://api.na.bambora.com/v1/payments
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-H "Content-Type: application/json"
-d '{
   "order_number":"10000123",
   "amount":100.00,
   "payment_method":"card",
   "card":{
      "name":"John Doe",
      "number":"5100000010001004",
      "expiry_month":"02",
      "expiry_year":"30",
      "cvd":"123"
   }
}'

Pre-auth and complete

For completions you will have to supply the Transaction Id {TransId} to the URL when using REST. The transId is returned from the pre-auth.

Copy

# Definition
# POST /v1/payments HTTP/1.1

curl https://api.na.bambora.com/v1/payments
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-H "Content-Type: application/json"
-d '{
   "order_number":"10000123",
   "amount":100.00,
   "payment_method":"card",
   "card":{
      "name":"John Doe",
      "number":"5100000010001004",
      "expiry_month":"02",
      "expiry_year":"14",
      "cvd":"123",
      "complete":false
   }
}'

#
# completion:
#

Definition
POST /v1/payments HTTP/1.1

Request
curl https://api.na.bambora.com/v1/payments/{transId}/completions
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-H "Content-Type: application/json"
-d '{
    "amount":59.33
}'

Single-use token

Single-use tokens provide a secure method of taking payments that reduces your PCI scope. You can take a payment using a token the same as you would take a payment with a credit card, the main difference being the ‘payment_method’ parameter and supplying the token.

To process a transaction using a token, you first need to have created a token. You can either do this from the browser/client using the Tokenization API or using the Browser SDKs .

A single-use token is a 'single-use nonce'. It is distinct from a multi-use Payment Profile token. See here .

Copy

Definition
POST /v1/payments HTTP/1.1

Request
curl https://api.na.bambora.com/v1/payments
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-H "Content-Type: application/json"
-d '{
    "payment_method":"token",
    "order_number":"MyOrderId-01234",
    "amount":15.99,
    "token":{
        "code":"gt7-0f2f20dd-777e-487e-b688-940b...",
        "name":"John Doe",
        "complete":true
    }
}'

Pre-auth and complete

Copy

Definition
POST /v1/payments HTTP/1.1

Request
curl https://api.na.bambora.com/v1/payments
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-H "Content-Type: application/json"
-d '{
    "payment_method":"token",
    "order_number":"MyOrderId-01234",
    "amount":15.99,
    "token":{
        "code":"gt7-0f2f20dd-777e-487e-b688-940b526172cd",
        "name":"John Doe",
        "complete":false
    }
}'

#
# completion:
#

Definition
POST /v1/payments HTTP/1.1

Request
curl https://api.na.bambora.com/v1/payments/{transId}/completions
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-H "Content-Type: application/json"
-d '{
    "amount":9.33
}'

Payment profile

Payment Profiles provide a secure method of taking payments that reduces your PCI scope. You can take a payment using a token the same as you would take a payment with a credit card, the main difference being you have to supply the Profile’s customer_code.

Before processing a transaction using a 'Payment Profile', you need to have created a one. See here .

A multi-use payment profile token is distinct from a single-use card token. See here .

Copy

Definition
POST /v1/payments HTTP/1.1

Request
curl https://api.na.bambora.com/v1/payments
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-H "Content-Type: application/json"
-d '{
    "payment_method":"payment_profile",
    "order_number":"UPDQWX1429722203",
    "amount":12.99,
    "payment_profile":{
        "customer_code":"053EF0CFD9b847dE8115ED21C2b1e7df",
        "card_id":1,
        "complete":true
    }
}'

Pre-auth and complete

Copy

Definition
POST /v1/payments HTTP/1.1

Request
curl https://api.na.bambora.com/v1/payments
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-H "Content-Type: application/json"
-d '{
    "payment_method":"payment_profile",
    "order_number":"UPDQWX1429722203",
    "amount":12.99,
    "payment_profile":{
        "customer_code":"053EF0CFD9b847dE8115ED21C2b1e7df",
        "card_id":1,
        "complete":false
    }
}'

#
# completion:
#

Definition
POST /v1/payments HTTP/1.1

Request
curl https://api.na.bambora.com/v1/payments/{transId}/completions
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-H "Content-Type: application/json"
-d '{
    "amount":9.20
}'

3D Secure

Copy

Definition
POST /v1/payments HTTP/1.1

Request
curl https://api.na.bambora.com/v1/payments \
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYUQ4MkQ5MTk3YjRjYzRiNzBhMjIxOTExZUU5Zjcw" \
-H "Content-Type: application/json" \
-d '{

   "amount": 250.01,
   "payment_method": "card",
   "customer_ip": "123.123.123.123"
   "card": {
      "name": "Test User",
      "number": "4012000033330026",
      "expiry_month": "09",
      "expiry_year": "20",
      "3d_secure": {
         "browser": {
            "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3",
            "java_enabled": "false",
            "language": "en-US",
            "color_depth": "24bits",
            "screen_height": 1080,
            "screen_width": 1920,
            "time_zone": -120,
            "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.90 Safari/537.36",
            "javascript_enabled": true,
         },
         "enabled": true,
         "version": 2,
         "authRequired": false
      }
   }
}'```

Verified by Visa (VbV), MasterCard SecureCode, and AMEX SafeKey are security features that prompt customers to enter a passcode when they pay by Visa, MasterCard, or AMEX. Merchants that want to integrate VbV, SecureCode, or SafeKey must have signed up for the service through their bank merchant account issuer. This service must also be enabled by our support team.

[//]: # (Use one of these two options to implement 3D Secure:)

[//]: # (* Use our API based 2-Step process.)
[//]: # (* Or use your own authentication process and pass the secure token data to our API.)

See [here](/docs/guides/3D_secure) for more information on how to implement 3D Secure.

Cash

If you receive a cash or cheque payment, you can record it through our REST API. We offer this payment method to help provide a centralized record of all your sales.

Copy

Gateway beanstream = new Gateway("v1",
    300200578,
    "4BaD82D9197b4cc4b70a221911eE9f70");

CashPaymentRequest cashReq = new CashPaymentRequest();
cashReq.setAmount(123.45);
cashReq.setOrderNumber("fancyPantsOrder001");

try {
    PaymentResponse response = beanstream.payments().makePayment(cashReq);
} catch (BeanstreamApiException ex) {
    //TODO handle error
}

Gateway bambora = new Gateway () {
    MerchantId = 300200578,
    PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70",
    ApiVersion = "1"
};
PaymentResponse response = bambora.Payments.MakePayment (
    new CashPaymentRequest () {
        Amount = 50.00,
        OrderNumber = "orderNum-GobBluth"
    }
);

$beanstream = new \Beanstream\Gateway('300200578', '4BaD82D9197b4cc4b70a221911eE9f70', 'www', 'v1');

$token_payment_data = array(
    'order_number' => "orderNum45678",
    'amount' => 100.0,
    'name' => 'Mrs. Testerson'
);

beanstream = gateway.Beanstream()
beanstream.configure(
        '300200578',
        payment_passcode='4BaD82D9197b4cc4b70a221911eE9f70')

txn = self.beanstream.record_cash_purchase(20)
resp = txn.commit()

Definition
POST /v1/payments HTTP/1.1

Request
curl https://api.na.bambora.com/v1/payments
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-H "Content-Type: application/json"
-d '{
    "payment_method":"cash",
    "order_number":"MyOrderId-01234",
    "amount":15.00
}'

Cheque

If you receive a cash or cheque payment, you can record it through our REST API. We offer this payment method to help provide a centralized record of all your sales.

Copy

Gateway beanstream = new Gateway("v1",
    300200578,
    "4BaD82D9197b4cc4b70a221911eE9f70");

ChequePaymentRequest chequeReq = new ChequePaymentRequest();
chequeReq.setAmount(12.99);
chequeReq.setOrderNumber("fancyPantsOrder002");

try {
    PaymentResponse response = beanstream.payments().makePayment(chequeReq);
} catch (BeanstreamApiException ex) {
    //TODO handle error
}

Gateway bambora = new Gateway () {
    MerchantId = 300200578,
    PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70",
    ApiVersion = "1"
};
PaymentResponse response = bambora.Payments.MakePayment (
    new ChequePaymentRequest () {
        Amount = 50.00,
        OrderNumber = "orderNum-TobiasFunke"
    }
);

$beanstream = new \Beanstream\Gateway('300200578', '4BaD82D9197b4cc4b70a221911eE9f70', 'www', 'v1');

$payment_data = array(
    'order_number' => "987654321",
    'amount' => 10.50
);

$result = $beanstream->payments()->makeChequePayment($payment_data);

beanstream = gateway.Beanstream()
beanstream.configure(
        '300200578',
        payment_passcode='4BaD82D9197b4cc4b70a221911eE9f70')

txn = self.beanstream.record_cheque_purchase(20)
resp = txn.commit()

Definition
POST /v1/payments HTTP/1.1

Request
curl https://api.na.bambora.com/v1/payments
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-H "Content-Type: application/json"
-d '{
    "payment_method":"cheque",
    "order_number":"MyOrderId-01234",
    "amount":15.00
}'

Voids

A Void will cancel a transaction before it is registered against a customer’s credit card account. Cardholders will never see a voided transaction on their credit card statement. As a result voids can only be attempted on the same day as the original transaction. After the end of day (roughly 11:59 PM EST/EDT), void requests will be rejected from the API if attempted. From that point on, for that transaction, you will need to perform a Return.

You can Void purchases and returns and you must supply the amount to void. This amount must equal the amount of that transaction, no more or less.

Copy

Definition
POST /v1/payments HTTP/1.1

Request
curl https://api.na.bambora.com/v1/payments/{transId}/void
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-H "Content-Type: application/json"
-d '{
    "amount":14.30
}'

Returns

Unreferenced returns

A Return will refund the customer part or all of the money from a transaction.

In order to perform a Return you must know the transaction ID from the purchase. This is returned in the response to the transaction.

You can return all or some of the original purchase amount.

Copy

PaymentResponse response = beanstream.payments().returnPayment(transactionId, 70.00);

PaymentResponse response = bambora.Payments.Return (response.TransactionId, 40.0);

$result = $beanstream->payments()->returnPayment($transaction_id, 12.99, $order_number);

 280001000,
    'order_number' => '10000123',
    'amount' => 500.00,
    'payment_method' => 'card',
    'card' => array(
        'name' => 'John Doe',
        'number' => '5100000010001004',
        'expiry_month' => '02',
        'expiry_year' => '14',
        'cvd' => '642'
    )
);   

curl_setopt($req,CURLOPT_POST, 1);
curl_setopt($req,CURLOPT_POSTFIELDS, json_encode($post));

$res_json = curl_exec($req);
$res = json_decode($res_json);

curl_close($req);

print_r($res);

?>

resp = beanstream.return_purchase(transaction_id, 12.99)

from urllib2 import Request, urlopen, HTTPError
import json

req_body = json.dumps({
    'merchant_id': 280001000,
    'order_number': '10000123',
    'amount': 500.00,
    'payment_method': 'card',
    'card': {
        'name': 'John Doe',
        'number': '5100000010001004',
        'expiry_month': '02',
        'expiry_year': '14',
        'cvd': '642'
    }
})

req = Request(
    'https://api.na.bambora.com/v1/payments/0/returns',
    data=req_body,
    headers={
        'Content-Type': 'application/json',
        'Authorization': 'Basic dXNlcm5hbWU6cGFzc3dvcmQ='
    })

try:
    # HTTP Request success
    response = json.loads(urlopen(req).read())
    print(response)
except HTTPError, e:
    # Handle errors here
    error = json.loads(e.read())
    print(error)

Definition
POST /v1/payments HTTP/1.1

Request
curl https://api.na.bambora.com/v1/payments/{transId}/returns
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-H "Content-Type: application/json"
-d '{
    "amount":12.50
}'

Definition
POST /v1/payments/0/returns HTTP/1.1

curl https://api.na.bambora.com/v1/payments/0/returns
-H "Authorization: Passcode MzAwMjAwNTc4OjRCYU..."
-d '{
   "merchant_id":280001000,
   "order_number":"10000123",
   "amount":500.00,
   "payment_method":"card",
   "card":{
      "name":"John Doe",
      "number":"5100000010001004",
      "expiry_month":"02",
      "expiry_year":"14",
      "cvd":"642"
   }
}'

Errors

You can read the errors returned by the API here .

Take payments

Include the Server SDK

Backend

Purchases and pre-auth's

Credit card

Backend

Pre-auth and complete

Backend

Single-use token

Backend

Pre-auth and complete

Backend

Payment profile

Backend

Pre-auth and complete

Backend

3D Secure

Backend

Cash

Backend

Cheque

Backend

Voids

Backend

Returns

Unreferenced returns

Backend

Errors