close
    Contents

    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

    // Step 1) Install module with NPM
    npm install beanstream-node
    
    // Step 2) Import module into your project
    var beanstream = require('beanstream-node')('merchantId', 'Payments API passcode', 'Profiles API passcode', 'Reporting API passcode');
    
    
    // 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';
    
    gem install beanstream --pre
    
    // 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
    
    // Go Get
    import beanstream "github.com/Beanstream/beanstream-go"
    

    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"
       }
    }'
    
    var beanstream = require('beanstream-node')('YOUR_MERCHANT_ID', 'YOUR_PAYMENTS_API_PASSCODE');
    
    var cardPayment = {
      order_number: 'order123456abc',
      amount:10.00,
      payment_method:"card",
      card:{
        name:"John Doe",
        number:"5100000010001004",
        expiry_month:"02",
        expiry_year:"19",
        cvd:"123"
      }
    };
    beanstream.payments.makePayment(cardPayment)
      .then(function(response){
        // display syccess
      })
      .catch(function(error){
        console.log(error);
        // display error
      });
    
    $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
    }
    
    begin
      result = Beanstream.PaymentsAPI.make_payment(
      {
        :order_number => PaymentsAPI.generateRandomOrderId("test"),
        :amount => 100,
        :payment_method => PaymentMethods::CARD,
        :card => {
          :name => "Mr. Card Testerson",
          :number => "4030000010001234",
          :expiry_month => "07",
          :expiry_year => "22",
          :cvd => "123",
          :complete => true
        }
      })
      puts "Success! TransactionID: #{result['id']}"
    
    rescue BeanstreamException => ex
      puts "Exception: #{ex.user_facing_message}"
    end
    
    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"
            }
        }
    );
    
    import (
      beanstream "github.com/Beanstream/beanstream-go"
      "github.com/Beanstream/beanstream-go/paymentMethods"
    )
    
    config := beanstream.DefaultConfig()
    config.MerchantId = "YOUR_MERCHANT_ID"
    config.PaymentsApiKey = "YOUR_PAYMENTS_API_PASSCODE"
    
    gateway := beanstream.Gateway{config}
    request := beanstream.PaymentRequest{
      PaymentMethod: paymentMethods.CARD,
      OrderNumber:   beanstream.Util_randOrderId(6),
      Amount:        12.99,
      Card: beanstream.CreditCard{
        Name:        "John Doe",
        Number:      "5100000010001004",
        ExpiryMonth: "11",
        ExpiryYear:  "19",
        Cvd:         "123",
        Complete:    true}} // set to false for pre-auth
    res, err := gateway.Payments().MakePayment(request)
    

    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:

    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
    }'
    
    var cardPayment = {
      order_number: 'order123456abc',
      amount:80.00,
      payment_method:"card",
      card:{
        name:"John Doe",
        number:"5100000010001004",
        expiry_month:"02",
        expiry_year:"19",
        cvd:"123",
        complete: false // false for pre-auth
      }
    };
    beanstream.payments.makePayment(cardPayment)
      .then(function(response){
        // approved
      })
      .catch(function(error){
        console.log(error);
      });
    
    // capture/complete a lesser amount
    beanstream.payments.completePayment(transId, {amount: 50.50})
      .then(function(result) {
        // payment captured/completed
      })
      .catch(function(error){
        console.log(error);
      });
    
    $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
    }
    
    begin
      result = Beanstream.PaymentsAPI.make_payment(
        {
          :order_number => PaymentsAPI.generateRandomOrderId("test"),
          :amount => 100,
          :payment_method => PaymentMethods::CARD,
          :card => {
            :name => "Mr. Card Testerson",
            :number => "4030000010001234",
            :expiry_month => "07",
            :expiry_year => "22",
            :cvd => "123",
            :complete => false #false makes it a pre-auth
          }
        }
      )
      puts "pre-authorized success: #{result}"
      transaction_id = result['id']
      puts "TransactionId: #{transaction_id}"
    
      result = Beanstream.PaymentsAPI.complete_preauth(transaction_id, 59.50)
      puts "completion success: #{result}"
    
    rescue BeanstreamException => ex
      puts "Exception: #{ex.user_facing_message}" # declined
    end
    
    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);
    
    import (
        beanstream "github.com/Beanstream/beanstream-go"
        "github.com/Beanstream/beanstream-go/paymentMethods"
    )
    
    config := beanstream.DefaultConfig()
    config.MerchantId = "300200578"
    config.PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70"
    
    gateway := beanstream.Gateway{config}
    request := beanstream.PaymentRequest{
        PaymentMethod: paymentMethods.CARD,
        OrderNumber:   beanstream.Util_randOrderId(6),
        Amount:        12.99,
        Card: beanstream.CreditCard{
            Name:        "John Doe",
            Number:      "5100000010001004",
            ExpiryMonth: "11",
            ExpiryYear:  "19",
            Cvd:         "123",
            Complete:    false}} // false for pre-auth
    res, err := gateway.Payments().MakePayment(request)
    // complete payment
    res2, err2 := gateway.Payments().CompletePayment(res.ID, 5.67)
    

    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
        }
    }'
    
    var tokenPayment = {
      order_number: 'order123456',
      amount:12.00,
      payment_method:"token",
      token:{
        name:"John Doe",
        code: myTokenString,
        complete: true
      }
    };
    beanstream.payments.makePayment(tokenPayment)
      .then(function(response){
        // display success
      })
      .catch(function(error){
        console.log(error);
      });
    
    $beanstream = new \Beanstream\Gateway('300200578', '4BaD82D9197b4cc4b70a221911eE9f70', 'www', 'v1');
    
    $legato_payment_data = array(
        'order_number' => "orderNum45678",
        'amount' => 100.0,
        'name' => 'Mrs. Legato Testerson'
    );
    try {
        $result = $beanstream->payments()->makeLegatoTokenPayment($token, $legato_payment_data, TRUE);
        print_r( $result );
    } catch (\Beanstream\Exception $e) {
        //handle exception
    }
    
    begin
      result = Beanstream.PaymentsAPI.make_payment(
        {
          :order_number => PaymentsAPI.generateRandomOrderId("test"),
          :amount => 13.99,
          :payment_method => PaymentMethods::TOKEN,
          :token => {
            :name => "Craig Test",
            :code => token, # add your token here
            :complete => true
          }
        }
      )
      puts "Success: #{result}"
    
    rescue BeanstreamException => ex
      puts "Error: #{ex.user_facing_message()}"
    end
    
    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(myLegatoToken);
    
    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 Legato token
                Name = "John Doe"
            }
        }
    );
    
    import (
        beanstream "github.com/Beanstream/beanstream-go"
        "github.com/Beanstream/beanstream-go/paymentMethods"
    )
    
    config := beanstream.DefaultConfig()
    config.MerchantId = "300200578"
    config.PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70"
    
    gateway := beanstream.Gateway{config}
    request := beanstream.PaymentRequest{
        PaymentMethod: paymentMethods.TOKEN,
        OrderNumber:   "order0012345",
        Amount:        15.99,
        Token: beanstream.Token{
            token,
            "John Doe",
            true}} // set to false for pre-auth
    res, err := gateway.Payments().MakePayment(request)
    

    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 Mobile or 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
    }'
    
    var tokenPayment = {
      order_number: 'order123456abc',
      amount:12.00,
      payment_method:"token",
      token:{
        name:"John Doe",
        code: myTokenString,
        complete: false // false for pre auth
      }
    };
    beanstream.payments.makePayment(tokenPayment)
      .then(function(response){
        // display success
      })
      .catch(function(error){
        console.log(error);
      });
    
    // capture/complete a lesser amount
    beanstream.payments.completePayment(transId, {amount: 50.50})
      .then(function(result) {
        // payment captured/completed
      })
      .catch(function(error){
        console.log(error);
      });
    
    $beanstream = new \Beanstream\Gateway('300200578', '4BaD82D9197b4cc4b70a221911eE9f70', 'www', 'v1');
    
    $legato_payment_data = array(
        'order_number' => "orderNum45678",
        'amount' => 100.0,
        'name' => 'Mrs. Legato Testerson'
    );
    try {
        $result = $beanstream->payments()->makeLegatoTokenPayment($token, $legato_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
    }
    
    begin
      result = Beanstream.PaymentsAPI.make_payment(
        {
          :order_number => PaymentsAPI.generateRandomOrderId("test"),
          :amount => 13.99,
          :payment_method => PaymentMethods::TOKEN,
          :token => {
            :name => "Gizmo Test",
            :code => token, # add your token here
            :complete => false #false makes it a pre-auth
          }
        }
      )
      puts "result: #{result}"
      transaction_id = result['id']
    
      result = Beanstream.PaymentsAPI.complete_preauth(transaction_id, 10.33)
      puts "completion result: #{result}"
    rescue BeanstreamException => ex
      puts "Error: #{ex.user_facing_message()}"
    end
    
    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(myLegatoToken);
    
    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 Legato token
                Name = "John Doe"
            }
        }
    );
    
    response = bambora.Payments.PreAuthCompletion (response.TransactionId, 15.45);
    
    import (
        beanstream "github.com/Beanstream/beanstream-go"
        "github.com/Beanstream/beanstream-go/paymentMethods"
    )
    
    config := beanstream.DefaultConfig()
    config.MerchantId = "300200578"
    config.PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70"
    
    gateway := beanstream.Gateway{config}
    request := beanstream.PaymentRequest{
        PaymentMethod: paymentMethods.TOKEN,
        OrderNumber:   "order0012345",
        Amount:        15.99,
        Token: beanstream.Token{
            token, // add your Legato token here
            "John Doe",
            false}} // false for pre-auth
    res, err := gateway.Payments().MakePayment(request)
    // complete payment
    res2, err2 := gateway.Payments().CompletePayment(res.ID, 5.67)
    

    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
        }
    }'
    
    var profilePayment = {
        order_number: 'order123456abc',
        amount:3.00,
        payment_method:"payment_profile",
        payment_profile:{
          customer_code: profileCustomerCode,
          card_id: 1,
          complete: true
        },
        comment: 'making a payment with a tokenized card on a payment profile.'
      };
    beanstream.payments.makePayment(profilePayment)
      .then(function(response){
        // display success
      })
      .catch(function(error){
        console.log(error);
      });
    
    $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
    }
    
    begin
      profile_payment = Beanstream.PaymentsAPI.getProfilePaymentRequestTemplate()
      profile_payment[:payment_profile][:customer_code] = profile_id
      profile_payment[:amount] = 77.50
      result = Beanstream.PaymentsAPI.make_payment(profile_payment)
    rescue BeanstreamException => ex
      puts "Error: #{ex.user_facing_message()}"
    end
    
    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
        }
    });
    
    import (
        beanstream "github.com/Beanstream/beanstream-go"
        "github.com/Beanstream/beanstream-go/paymentMethods"
    )
    
    config := beanstream.DefaultConfig()
    config.MerchantId = "300200578"
    config.PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70"
    
    gateway := beanstream.Gateway{config}
    payment := beanstream.PaymentRequest{
        PaymentMethod: paymentMethods.PROFILE,
        OrderNumber:   "orderId000345",
        Amount:        12.99,
        Profile: beanstream.ProfilePayment{
            res.Id,
            1,
            true}} // set to false for pre-auth
    res, err := gateway.Payments().MakePayment(payment)
    

    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
    }'
    
    var profilePayment = {
        order_number: 'order123456abc',
        amount:3.00,
        payment_method:"payment_profile",
        payment_profile:{
          customer_code: profileCustomerCode,
          card_id: 1,
          complete: false
        },
        comment: 'making a payment with a tokenized card on a payment profile.'
      };
    beanstream.payments.makePayment(profilePayment)
      .then(function(response){
        // display success
      })
      .catch(function(error){
        console.log(error);
      });
    
    // capture/complete a lesser amount
    beanstream.payments.completePayment(transId, {amount: 50.50})
      .then(function(result) {
        // payment captured/completed
      })
      .catch(function(error){
        console.log(error);
      });
    
    $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
    }
    
    begin
      # pre-auth
      profile_payment = Beanstream.PaymentsAPI.getProfilePaymentRequestTemplate()
      profile_payment[:amount] = 80
      profile_payment[:payment_profile][:customer_code] = profile_id
      profile_payment[:payment_profile][:complete] = false #false for pre-auth
      result = Beanstream.PaymentsAPI.make_payment(profile_payment)
    
      #complete pre-auth
      result = Beanstream.PaymentsAPI.complete_preauth(result['id'], 40.50)
      puts "success: #{result}"
    rescue BeanstreamException => ex
      puts "Error: #{ex.user_facing_message()}"
    end
    
    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);
    
    import (
        beanstream "github.com/Beanstream/beanstream-go"
        "github.com/Beanstream/beanstream-go/paymentMethods"
    )
    
    config := beanstream.DefaultConfig()
    config.MerchantId = "300200578"
    config.PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70"
    
    gateway := beanstream.Gateway{config}
    payment := beanstream.PaymentRequest{
        PaymentMethod: paymentMethods.PROFILE,
        OrderNumber:   "orderId000345",
        Amount:        12.99,
        Profile: beanstream.ProfilePayment{
            res.Id,
            1,
            false}} // false for pre-auth
    res, err := gateway.Payments().MakePayment(payment)
    // complete payment
    res2, err2 := gateway.Payments().CompletePayment(res.ID, 5.67)
    

    Interac Online

    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 '{
          "order_number":"MyOrderId-01234",
          "amount":100.00,
          "payment_method":"interac"     
        }'
    

    Interac Online is a transaction method available to Canadian merchants only. It allows customers to authenticate direct debits without sharing their debit card details with the merchant.

    See here for more information on how to implement Interac Online.

    3D Secure

    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"
          },
          "term_url":"https://myserver.com/redirect/3ds"
        }'
    

    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.

    See here 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');
    
    $legato_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"
        }
    );
    
    import (
        beanstream "github.com/Beanstream-DRWP/beanstream-go"
        "github.com/Beanstream-DRWP/beanstream-go/paymentMethods"
    )
    
    config := beanstream.DefaultConfig()
    config.MerchantId = "300200578"
    config.PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70"
    
    gateway := beanstream.Gateway{config}
    request := beanstream.PaymentRequest{
        PaymentMethod: paymentMethods.CASH,
        OrderNumber:   "order12345b",
        Amount:        12.00}
    res, err := gateway.Payments().MakePayment(request)
    

    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"
        }
    );
    
    import (
        beanstream "github.com/Beanstream-DRWP/beanstream-go"
        "github.com/Beanstream-DRWP/beanstream-go/paymentMethods"
    )
    
    config := beanstream.DefaultConfig()
    config.MerchantId = "300200578"
    config.PaymentsApiKey = "4BaD82D9197b4cc4b70a221911eE9f70"
    
    gateway := beanstream.Gateway{config}
    request := beanstream.PaymentRequest{
        PaymentMethod: paymentMethods.CHEQUE,
        OrderNumber:   "order12345b",
        Amount:        12.00}
    res, err := gateway.Payments().MakePayment(request)
    

    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
    }'
    
    beanstream.payments.voidPayment(transId, {amount: 30})
      .then(function(result) {
        // success
      })
      .catch(function(error){
        console.log(error);
      });
    
    $result = $beanstream->payments()->voidPayment($transaction_id, 12.99);
    
    void_result = Beanstream.PaymentsAPI.void_payment(transaction_id, 100)
    
    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);
    
    res, err := gateway.Payments().VoidPayment(transactionId, 12.99)
    

    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
    }'
    
    beanstream.payments.returnPayment(transId, {amount: 40})
      .then(function(result) {
        // success
      })
      .catch(function(error){
        console.log(error);
      });
    
    $result = $beanstream->payments()->returnPayment($transaction_id, 12.99, $order_number);
    
    return_result = Beanstream.PaymentsAPI.return_payment(transaction_id, 100)
    
    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);
    
    res, err := gateway.Payments().ReturnPayment(transactionId, 12.99)
    

    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);
    
    ?>
    
    require 'open-uri'
    require 'net/http'
    require 'json'
    
    uri = URI('https://api.na.bambora.com/v1/payments/0/returns')
    req = Net::HTTP::Post.new(uri.path) # Ruby 2.0: use .new(uri) instead
    req['Content-Type'] = 'application/json'
    req['Authorization'] = 'Basic dXNlcm5hbWU6cGFzc3dvcmQ='
    
    req.body = {
       :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'
       }
    }.to_json
    
    res = Net::HTTP.start(uri.hostname, uri.port, :use_ssl => true) { |http|
        http.request(req)
    }
    
    puts "\nUNREFERENCED RETURN"
    puts res.inspect
    puts res.body
    
    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.