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

    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"
       }
    }'
    

    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
    }'
    

    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
        }
    }'
    

    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
    }'
    

    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
        }
    }'
    

    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
    }'
    

    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
    }'
    

    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
    }'
    

    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
    }'
    

    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
    }'
    

    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"
       }
    }'
    

    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.