When a merchant uses Bambora's Batch processing, they can process multiple credit card or direct payments (EBP/ACH) transactions by submitting a single file to Bambora for processing. Unlike other services offered by Bambora, Batch Processing is technically an offline process, as transactions are not processed immediately after data is received in our system.
Merchants can use the Bambora batch services to prepare a file in advance and schedule billings for a later processing date. Direct payment files start processing after 11:00 am (PST) and, credit card files process early morning (PST). For the Credit card files, you also have the option to process them immediately after uploading the file.
Bank payments (EBP & ACH transactions) take about three business days (your credit date may be higher or lower as it is based on the credit lag time that is configured in your account) to complete because banks need that time to exchange records and update their systems.
The Bambora Batch Processing service accepts files that follow the comma separated (CSV) format. Files must have a file extension of either .csv or .txt.
Profiles API - Endpoint
In order to store or modify information within a Payment Profile, you will need to make an API call against the Secure Payment Profiles API:
Profiles API – request variables
A full API integration allows a merchant to create new profiles and query, modify profiles, and store multiple cards per account using three different operation types.
operationType=N -- Create a New profile tied to one individual, assigning and validating a single credit card. Additionally, billing, language and custom reference information, a customer code, account number group, and velocity limits can be input at that time.
operationType=M -- Modify billing information, language, and custom reference fields; change an existing card; process a validation against that updated card; and assign different groups, velocity limits and account numbers.
operationType=Q -- Query a profile for a list of information associated with a profile including billing data, masked card number (last four digits visible only), groups and account numbers, velocity limits, language, and ID numbers for each of the cards associated with the profile.
These are the required input variables. to complete the operations described above.
|Group||Variable||New (N)||Modify (M)||Query (Q)||Description|
|Basic API call||operationType||R||R||R||N – Create a New profile
M – Modify an existing profile
Q – Query an existing profile
|serviceVersion||R||R||R||1.0 for the current version.|
|merchantId||R||R||R||Pass the merchant’s unique Bambora identification number. Bambora issues one merchant ID per currency. If the merchant is processing in both Canadian and US dollars, complete one full integration per merchant ID number. Note: This field is different than the merchantid field used in the Process Transaction API.|
|subMerchantId||O||O||O||Used for parent/ISV level processing. If used then merchantId and passCode must match the parent level account, subMerchantId will match the individual sub account being targetted with the operation. This service needs to be enabled prior to usage, please contact Customer Experience if authentication fails.|
|Important! Use only one of the next two variables. Use passCode OR use hashValue|
|passCode||→||→||→||Specify the API access passCode generated on the payment profile configuration page.
Note: If using an XML formatted request, you must use passCode; if using a Querystring formatted request, you can use either passCode (or hashValue).
|hashValue||→||→||→||If you are using a Querystring formatted request, you can use hashValue (or passCode).|
|responseFormat||R||R||R||XML – eXtensible Markup Language
QS – Querystring
|Specify Customer Code (or token)||customerCode||O||R||R||Token used to identify the profile in transactions.
New profiles: Submit a value up to 32 characters—leave blank to use a system generated value.
Existing profile: Reference the customerCode associated with the profile. customerCode cannot be modified after it is assigned to a profile.
|Specify an “Order Number”||trnOrderNumber||O||O||O||By assigning a unique order number with each request to create or modify a profile, merchants can process status requests to query response messages. Maximum 30 alphanumeric characters.|
|Activate, disable, or close profiles||status||N/A||O||N/A||A – Payments can be processed against the profile.
D – Payments cannot be processed against the profile. If needed, the profile can be reactivated at a later date.
C – No payments can be processed against the profile. If needed, the profile can be reactivated at a later date. When modifying an existing profile, use this field in conjunction with operationType=M
|Collect credit card details||trnCardOwner||O||O||N/A||Name of the card owner as it ison their credit card. Required for new customer profiles. Maximum 64 alphanumeric characters.|
|trnCardNumber||O||O||N/A||Specify the credit card number as it is on the card. Required for new customer profiles.|
|trnExpMonth||O||O||N/A||Credit card expiration month. Format: two-digits. e.g. 09 = September. Required for new customer profiles.|
|trnExpYear||O||O||N/A||Credit card expiration year. Format: two-digits. e.g. 17 = 2017. Required for new customer profiles.|
|trnCardCvd||O||→||N/A||3-digit CVD number from the back of the customer’s credit card. This variable is not stored in the customer profile. CVD numbers are optional unless Require Credit Card CVD is enabled in the Bambora Order Settings.|
|Validate card information on new accounts||cardValidation||→||→||N/A||Optional flag so merchants can validate a customer profile by processing a small pre-authorization when the is created. In the majority of scenarios, the pre-authorization will be $0.50. For Bambora Canada or TD issued Visa merchant accounts only, the [MB1] pre-authorization will register at $0.
0 – Do not perform validation
1 – Perform validation
|EBP Bank payments. *Limited availability service for pre-approved custom clients. Before integrating contact: Bambora Customer Experience||bankAccountType||R||O||N/A||Type of bank account belonging to the customer. Merchants can only process in the currency of their Bambora account. Options for merchants processing in Canadian currency.
CA – Canadian dollar account from a Canadian Bank
|bankAccountHolder||R||O||N/A||Name of the account holder.|
|institutionNumber||R||O||N/A||For Canadian bank accounts only. The customer's 3-digit financial institution number.|
|branchNumber||R||O||N/A||For Canadian bank accounts only. The customer’s 5-digit bank transit/branch number.|
|routingNumber||R||O||N/A||For US bank accounts only. The customer’s 9-digit routing number.|
|accountNumber||R||O||N/A||For US and Canadian bank accounts. The customer’s bank account number. Account number can vary in length; maximum 17 digits.|
|ACH Bank Payments. * Limited availability service for pre-approved custom clients. Before integrating contact Bambora Customer Experience||bankAccountType||R||O||N/A||Options for merchants processing in US currency.
PC – US Personal Checking account
PS – US Personal Saving account
CC – US Corporate Checking account
CS – US Corporate Savings account
|bankAccountHolder||R||O||N/A||Account holder name,|
|institutionNumber||R||O||N/A||Canadian bank accounts only. The customer's 3-digit financial institution number.|
|branchNumber||R||O||N/A||Canadian bank accounts: The customer’s 5-digit bank transit/branch number.
US bank accounts: The first 9-digits on the customer’s check.
|accountNumber||R||O||N/A||US and Canadian bank accounts. The customer’s bank account number. Account number can vary in length. Maximum 17 digits.|
|routingNumber||R||O||N/A||US bank accounts only. Customer’s 9-digit routing number.|
|Collect additional contact details||ordName||O||→||N/A||Specify a primary billing contact name. Maximum 64 alphanumeric characters. Mandatory if you are using preventing duplicate profiles.|
|ordAddress1||O||O||N/A||Billing address. Maximum 32 alphanumeric characters.|
|ordAddress2||O||O||N/A||Additional 32 alphanumeric characters for longer addresses.|
|ordCity||O||O||N/A||City name for billing information.|
|ordProvince||O||O||N/A||Valid province/state code|
|ordCountry||O||O||N/A||Valid country code|
|ordPostalCode||O||O||N/A||Billing address postal/zip code.|
|ordEmailAddress||O||O||N/A||Email address for the primary contact.|
|ordPhoneNumber||O||O||N/A||Primary contact phone number for billing information.|
|trnLanguage||O||O||N/A||Default is ENG for English. Submit FRE to direct customers to a French version of the web form.|
|velocityIdentity||O||O||N/A||Velocity groups are used to limit the dollar amount that a profile owner can spend over a specific period. Assign profiles to the appropriate group by passing a velocity ID value in this variable. Velocity ID values can be up to 8 alphanumeric characters. You cannot assign more than one ID to a profile.|
|profileGroup||O||O||N/A||You can group payment profiles into categories. You can then specify the group ID number in this variable.|
|Specify language||ref1, ref2, ref3, ref4, ref5||O||O||N/A||Pass unique profile data using up to 5 custom reference variables. Data in these fields are returned to the Return URL and stored in the shopper profile. Maximum 255 alphanumeric characters per field.|
|Assign Velocity Group||function||N/A||N/A||N/A||Used with the ADD_CARD operation only.
DEF – Default
SEC – Secondary card
|Assign Status Group||incAllCreditCards||N/A||N/A||N/A||When used with responseFormat=XML, this option returns all credit cards on profile.
1 – Returns all cards.
0 – Return the default card only.
Payment Profile API – response variables
These variables are returned to the Response Notification URL specified in the Order Settings. To add or make changes to the URL, log into the Bambora membership area and navigate to administration> account settings> order settings. In the Response Notification section, in the Secure Payment Profile field, specify the URL.
|Basic Response Variables||responseCode||For the profile creation or modification request status, returns a numeric code. Response codes and descriptions|
|responseMessage||Description of the reponseCode.|
|customerCode||This unique token string identifies the customer profile.
If a specific customerCode was passed during the original request, the same data is returned here.
If no customerCode was passed, Bambora responds with a randomly generated, secure token.
This customerCode is then passed to the Process Transaction API in place of payment details when processing a transaction against the customer profile.
|trnOrderNumber||If an order number was specified in the initial request, that value is returned.
If no number was specified, an auto-generated order number is returned.
This order number is a unique identifier for the profile creation or modification request.
|cardType||VI – Visa
MC – MasterCard
AM – American Express
DI – Diners Club
NN – Discover
JB – JCB
NW – NextWave
SE – Sears
|cardNumber||Customer card number showing the first digit and last four digits.|
|If using card validation||trnApprove||If card validation was used in the request, a value is returned to indicate if the pre-authorization transaction was approved.
1 – Approved
0 – Declined
|trnId||Returns the unique transaction identification number for the card validating pre-authorization transaction.|
|messageId||Numeric code. Indicates the card validation transaction approved/declined status. This is the same as the messageID from the Bambora Process Transaction API.|
|messageText||Description of the messageId|
|trnOrderNumber||The order number assigned to the card verification transaction is returned.
If an order number was specified in the initial request, that value is returned.
If no number was specified, an auto-generated order number is returned.
|authCode||If the pre-authorization transaction is approved this parameter contains a unique bank authorization code.|
|trnAmount||Amount processed on the card verification transaction.|
|cvdId||Card verification transaction for the CVD response code.
1 – CVD Match
2 – CVD Mismatch
3 – CVD Not Verified
4 – CVD Should have been present
5 – CVD Issuer unable to process request
6 – CVD Not Provided
|Where custom profile data was passed||ref1, ref2, ref3, ref4, ref5||Any custom reference fields passed in with the request are returned unmodified in the response.|
|Where responseFormat=XML in the original API request||cardNode||Designed for situations where multiple cards have been stored per profile. One node per card is returned including these values:
function (DEF or SEC)
Payment Profiles API – customer response codes