Take Payments
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
// 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
// Maven
<repositories>
<repository>
<id>snapshots-repo</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
<releases><enabled>false</enabled></releases>
<snapshots><enabled>true</enabled></snapshots>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.beanstream.api</groupId>
<artifactId>beanstream</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
</dependencies>
//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
Select the programming language of your project from the tabs at the top of the right-hand column.
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
# 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"
}
}'
$beanstream = new \Beanstream\Gateway('YOUR_MERCHANT_ID', 'YOUR_PAYMENTS_API_PASSCODE', 'www', 'v1');
$payment_data = array(
'order_number' => 'orderNumber0023',
'amount' => 19.99,
'payment_method' => 'card',
'card' => array(
'name' => 'Mr. Card Testerson',
'number' => '4030000010001234',
'expiry_month' => '07',
'expiry_year' => '22',
'cvd' => '123'
)
);
try {
$result = $beanstream->payments()->makeCardPayment($payment_data, TRUE); //set to FALSE for Pre-Auth
print_r( $result );
} catch (\Beanstream\Exception $e) {
//handle exception
}
beanstream = gateway.Beanstream()
beanstream.configure(
'YOUR_MERCHANT_ID',
payment_passcode='YOUR_PAYMENTS_API_PASSCODE')
card = billing.CreditCard(
'John Doe',
'4030000010001234',
'03',
'2019',
'123')
trans = beanstream.purchase(51.32, card)
resp = trans.commit()
Gateway beanstream = new Gateway("v1",
YOUR_MERCHANT_ID,
"YOUR_PAYMENTS_API_PASSCODE");
CardPaymentRequest req = new CardPaymentRequest();
req.setAmount(100.0);
req.setOrderNumber("orderNum000112");
req.getCard()
.setName("John Doe")
.setNumber("5100000010001004")
.setExpiryMonth("12")
.setExpiryYear("18")
.setCvd("123");
try {
PaymentResponse response = beanstream.payments().makePayment(req);
System.out.println("Card Payment Approved? "+ response.isApproved());
} catch (BeanstreamApiException ex) {
// todo handle error
}
Gateway bambora = new Gateway () {
MerchantId = YOUR_MERCHANT_ID,
PaymentsApiKey = "YOUR_PAYMENTS_API_PASSCODE",
ApiVersion = "1"
};
PaymentResponse response = bambora.Payments.MakePayment (
new CardPaymentRequest {
Amount = 100.00,
OrderNumber = "orderNum002233",
Card = new Card {
Name = "John Doe",
Number = "5100000010001004",
ExpiryMonth = "12",
ExpiryYear = "18",
Cvd = "123"
}
}
);
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.
Note:
- 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"
Pre-Auth and Complete
# 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
}'
$beanstream = new \Beanstream\Gateway('300200578', '4BaD82D9197b4cc4b70a221911eE9f70', 'www', 'v1');
$payment_data = array(
'order_number' => 'orderNumber002y',
'amount' => 19.99,
'payment_method' => 'card',
'card' => array(
'name' => 'Mr. Card Testerson',
'number' => '4030000010001234',
'expiry_month' => '07',
'expiry_year' => '22',
'cvd' => '123'
)
);
try {
$result = $beanstream->payments()->makeCardPayment($payment_data, FALSE); //set to FALSE for Pre-Auth
$transaction_id = $result['id'];
// complete payment
$result = $beanstream->payments()->complete($transaction_id, 12.5);
print_r( $result );
} catch (\Beanstream\Exception $e) {
//todo handle exception
}
beanstream = gateway.Beanstream()
beanstream.configure(
'300200578',
payment_passcode='4BaD82D9197b4cc4b70a221911eE9f70')
card = billing.CreditCard(
'John Doe',
'4030000010001234',
'03',
'2019',
'123')
trans = beanstream.preauth(51.32, card)
resp = trans.commit()
trans2 = beanstream.preauth_completion(resp.transaction_id(), 25.00)
resp2 = trans2.commit()
Gateway beanstream = new Gateway("v1",
300200578,
"4BaD82D9197b4cc4b70a221911eE9f70");
CardPaymentRequest paymentRequest = new CardPaymentRequest();
paymentRequest.setAmount(90.0);
paymentRequest.setMerchantId("300200578");
paymentRequest.setOrderNumber("order00345");
paymentRequest.getCard()
.setName("John Doe")
.setNumber("5100000010001004")
.setExpiryMonth("12")
.setExpiryYear("18")
.setCvd("123");
try {
PaymentResponse response = beanstream.payments().preAuth(paymentRequest);
PaymentResponse authResp = beanstream.payments().preAuthCompletion(response.id, 43.50, null);
} catch (BeanstreamApiException ex) {
}
Gateway bambora = new Gateway () {
MerchantId = 300200578,
PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70",
ApiVersion = "1"
};
PaymentResponse response = bambora.Payments.PreAuth (
new CardPaymentRequest {
Amount = 100.00,
OrderNumber = getRandomOrderId("test"),
Card = new Card {
Name = "John Doe",
Number = "5100000010001004",
ExpiryMonth = "12",
ExpiryYear = "18",
Cvd = "123"
}
}
);
PaymentResponse response2 = bambora.Payments.PreAuthCompletion (response.TransactionId, 35.99);
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.
Single-use Token
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
}
}'
$beanstream = new \Beanstream\Gateway('300200578', '4BaD82D9197b4cc4b70a221911eE9f70', 'www', 'v1');
$token_payment_data = array(
'order_number' => "orderNum45678",
'amount' => 100.0,
'name' => 'Mrs. Token Testerson'
);
try {
$result = $beanstream->payments()->makeSingleUseTokenPayment($token, $token_payment_data, TRUE);
print_r( $result );
} catch (\Beanstream\Exception $e) {
//handle exception
}
beanstream = gateway.Beanstream()
beanstream.configure(
'300200578',
payment_passcode='4BaD82D9197b4cc4b70a221911eE9f70')
txn = beanstream.purchase_with_token(22.13, token)
txn.set_cardholder_name("Gizmo")
resp = txn.commit()
Gateway beanstream = new Gateway("v1",
300200578,
"4BaD82D9197b4cc4b70a221911eE9f70");
TokenPaymentRequest tokenReq = new TokenPaymentRequest();
tokenReq.setAmount(100.00);
tokenReq.setOrderNumber("myOrder9999");
tokenReq.getToken()
.setName("John Doe")
.setCode(myToken);
try {
PaymentResponse response = beanstream.payments().makePayment(tokenReq);
System.out.println("Token Payment Approved? "+ response.isApproved());
} catch (BeanstreamApiException ex) {
//TODO handle exception
}
Gateway bambora = new Gateway () {
MerchantId = 300200578,
PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70",
ApiVersion = "1"
};
PaymentResponse response = bambora.Payments.MakePayment (
new TokenPaymentRequest ()
{
Amount = 30.0,
OrderNumber = "myOrder88888",
Token = new Token {
Code = token, // your single use token
Name = "John Doe"
}
}
);
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.
Pre-Auth and Complete
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
}'
$beanstream = new \Beanstream\Gateway('300200578', '4BaD82D9197b4cc4b70a221911eE9f70', 'www', 'v1');
$token_payment_data = array(
'order_number' => "orderNum45678",
'amount' => 100.0,
'name' => 'Mrs. Token Testerson'
);
try {
$result = $beanstream->payments()->makeTokenPayment($token, $token_payment_data, FALSE);//set to FALSE for Pre-Auth
$transaction_id = $result['id'];
// complete payment
$result = $beanstream->payments()->complete($transaction_id, 12.5);
print_r( $result );
} catch (\Beanstream\Exception $e) {
//todo handle exception
}
beanstream = gateway.Beanstream()
beanstream.configure(
'300200578',
payment_passcode='4BaD82D9197b4cc4b70a221911eE9f70')
txn = beanstream.preauth_with_token(50.0, token)
txn.set_cardholder_name("Gizmo")
resp = txn.commit()
# complete payment
trans2 = beanstream.preauth_completion(resp.transaction_id(), 25.00)
resp2 = trans2.commit()
Gateway beanstream = new Gateway("v1",
300200578,
"4BaD82D9197b4cc4b70a221911eE9f70");
TokenPaymentRequest req = new TokenPaymentRequest();
req.setAmount(80.00);
req.setOrderNumber("myOrder77777");
req.getToken()
.setName("John Doe")
.setCode(mySingleUseToken);
try {
PaymentResponse response = beanstream.payments().preAuth(req);
// complete payment
response = beanstream.payments().preAuthCompletion(response.id, 55.30, response.orderNumber);
} catch (BeanstreamApiException ex) {
//todo handle error
}
Gateway bambora = new Gateway () {
MerchantId = 300200578,
PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70",
ApiVersion = "1"
};
PaymentResponse response = bambora.Payments.PreAuth (
new TokenPaymentRequest ()
{
Amount = 30,
OrderNumber = "orderNumber66666",
Token = new Token {
Code = token, // your single use token
Name = "John Doe"
}
}
);
response = bambora.Payments.PreAuthCompletion (response.TransactionId, 15.45);
Payment Profile
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
}
}'
$beanstream = new \Beanstream\Gateway('300200578', '4BaD82D9197b4cc4b70a221911eE9f70', 'www', 'v1');
$profile_payment_data = array(
'order_number' => "abc123",
'amount' => 75.50
);
try {
$result = $beanstream->payments()->makeProfilePayment($profile_id, 1, $profile_payment_data, TRUE); //set to FALSE for Pre-Auth
print_r( $result );
} catch (\Beanstream\Exception $e) {
//handle exception
}
beanstream = gateway.Beanstream()
beanstream.configure(
'300200578',
payment_passcode='4BaD82D9197b4cc4b70a221911eE9f70')
trans = beanstream.purchase_with_payment_profile(50.43, profile_id)
resp = trans.commit()
Gateway beanstream = new Gateway("v1",
300200578,
"4BaD82D9197b4cc4b70a221911eE9f70");
ProfilePaymentRequest req = new ProfilePaymentRequest();
req.setProfile(new ProfilePaymentRequestData()
.setCardId(1)
.setCustomerCode(profile.getId()));
req.setAmount(13);
req.setOrderNumber("myOrderId00002");
try {
PaymentResponse response = beanstream.payments().makePayment(req);
System.out.println("Card Payment Approved? "+ response.isApproved());
} catch (BeanstreamApiException ex) {
// todo handle error
}
Gateway bambora = new Gateway () {
MerchantId = 300200578,
PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70",
ApiVersion = "1"
};
PaymentResponse payment = bambora.Payments.MakePayment (new ProfilePaymentRequest() {
Amount = 40.95,
OrderNumber = "myOrder002233",
PaymentProfile = new PaymentProfileField() {
CardId = 1,
CustomerCode = profile_id
}
});
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.
Pre-Auth and Complete
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
}'
$beanstream = new \Beanstream\Gateway('300200578', '4BaD82D9197b4cc4b70a221911eE9f70', 'www', 'v1');
$profile_payment_data = array(
'order_number' => "abc123",
'amount' => 75.50
);
try {
$result = $beanstream->payments()->makeProfilePayment($profile_id, 1, $profile_payment_data, FALSE); // FALSE for Pre-Auth
$transaction_id = $result['id'];
// complete payment
$result = $beanstream->payments()->complete($transaction_id, 12.5);
print_r( $result );
} catch (\Beanstream\Exception $e) {
//todo handle exception
}
txn = beanstream.preauth_profile(60, customer_code)
resp = txn.commit()
trans = beanstream.preauth_completion(resp.transaction_id(), 25.00)
Gateway beanstream = new Gateway("v1",
300200578,
"4BaD82D9197b4cc4b70a221911eE9f70");
ProfilePaymentRequest req = new ProfilePaymentRequest();
req.setProfile(new ProfilePaymentRequestData()
.setCardId(1)
.setCustomerCode(profile.getId()));
req.setAmount(130);
req.setOrderNumber("myOrderId00002");
try {
PaymentResponse result = beanstream.payments().preAuth(paymentRequest);
// complete the pre-auth
result = beanstream.payments().preAuthCompletion(result.id, 100, null);
} catch (BeanstreamApiException ex) {
// todo handle error
}
Gateway bambora = new Gateway () {
MerchantId = 300200578,
PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70",
ApiVersion = "1"
};
// pre-auth
PaymentResponse payment = bambora.Payments.PreAuth (new ProfilePaymentRequest() {
Amount = 50,
OrderNumber = "myFancyOrderID-1234",
PaymentProfile = new PaymentProfileField() {
CardId = 1,
CustomerCode = response.Id
}
});
// complete payment
payment = bambora.Payments.PreAuthCompletion (payment.TransactionId, 15.12);
3D Secure
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
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
}'
$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()
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"
}
);
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.
Cheque
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
}'
$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()
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"
}
);
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.
Voids
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
}'
$result = $beanstream->payments()->voidPayment($transaction_id, 12.99);
resp = beanstream.void_purchase(transaction_id, 12.99)
''' OR for voiding returns: '''
resp = beanstream.void_return(transaction_id, 12.99)
PaymentResponse response = beanstream.payments().voidPayment(transactionId, 70.00);
PaymentResponse response = bambora.Payments.Void (response.TransactionId, 30);
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.
Returns
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
}'
$result = $beanstream->payments()->returnPayment($transaction_id, 12.99, $order_number);
resp = beanstream.return_purchase(transaction_id, 12.99)
PaymentResponse response = beanstream.payments().returnPayment(transactionId, 70.00);
PaymentResponse response = bambora.Payments.Return (response.TransactionId, 40.0);
Unreferenced Returns
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"
}
}'
<?php
$req = curl_init('https://api.na.bambora.com/v1/payments/0/returns');
$headers = array(
'Content-Type:application/json',
'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='
);
curl_setopt($req,CURLOPT_HTTPHEADER, $headers);
curl_setopt($req,CURLOPT_RETURNTRANSFER, 1);
curl_setopt($req,CURLOPT_HEADER, 0);
$post = array(
'merchant_id' => 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);
?>
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)
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.
Errors
You can read the errors returned by the API here.