Merchants and integrated partners can securely and compliantly store customer bank account information in Bambora's Secure Payment Profile service, to be used for later payments through the Batch Processing system.
In order to manage this information API calls can be made to create New (N) profiles, Modify (M) existing profiles to change the stored information, or Query (Q) profiles to see the status of them.
For information about the Batch Processing service and formats of the files themselves please refer to the Developer portal guide on Batch Payments.
Batch Payments Profile 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:
Requests to this endpoint should be querystring formatted using proper URL encoding using a HTTPS POST method. The Content-Type header needs to be set to "application/x-www-form-urlencoded".
Here is an example:
POST https://web.na.bambora.com/scripts/payment_profile.asp HTTP/1.1
HTTP/1.1 200 OK
The server response will include whatever information is applicable to the profile in question, such as name and address, billing information, custom data fields, and type of bank account. The Content-Type header will be set to either "text/html" if it is a querystring formatted response or "text/xml" if it is a XML formatted response (based on the responseFormat request field).
Profiles API – Request Variables
A full API integration allows a merchant to create new profiles and query, modify profiles, and store bank accounts in a profile using three different operation types.
operationType=N -- Create a New profile tied to one individual, assigning and validating the format of a single bank account. 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 account; process a validation against that updated account; 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, groups and account numbers, velocity limits, language.
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.3 for the current version.|
|merchantId||R||R||R||Pass the merchant’s unique Bambora identification number in order to authenticate against the API. If this is a direct-to-merchant integration then use your assigned MID; if this is an integrated partner integration then you can use your Channel Partner (CP) MID and associated passCode, and include the subMerchantId as a secondary identifier for the account you want to create the profile within.|
|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 targeted with the operation. This service needs to be enabled prior to usage, please contact Customer Experience if authentication fails.|
|passCode||R||R||R||Specify the API access passCode generated on the Payment Profile configuration page.|
This controls the format of the response as well as what Content-Type is returned (see explanation above).
XML – eXtensible Markup Language
|Specify Customer Code||customerCode||O||R||R||
Merchant-level unique ID used to identify the profile in transactions.
|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
|Direct Debit/Direct Payment Bank payments (EFT).
*Limited availability service for pre-approved custom clients. Before integrating contact: Bambora Customer Experience
|bankAccountType||R||O||N/A||For merchants domiciled in Canada.
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.|
|accountNumber||R||O||N/A||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 domiciled in the USA.
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,|
|accountNumber||R||O||N/A||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 ABA routing number.|
|Custom Data Fields||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 customer's profile. Maximum 255 alphanumeric characters per field.|
Payment Profile API – Response Variables
These variables are returned from the Bambora API for all operation types, and can be used to understand the result of the request. In addition, if there is a URL entered into the Payment Profile Response Notification field in the Order Settings in the Bambora Merchant Portal then a duplicate response is submitted to that URL with a querystring formatted POST method. To add or make changes to the URL, log into the Bambora Merchant Portal 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||customerCode||This unique ID 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 used with the Batch Processing API in order to process payments against the stored information.
|responseCode||For the profile creation or modification request status, returns a numeric code. See list of Response Code IDs in the following table.|
|responseMessage||Description of the reponseCode.|
|httpStatusCode||The API returns a HTTP status code that can be used to determine the general status of the request.
200 -- Successful
400 -- Bad Request
401 -- Authentication Failure
402 -- Business Rule Violation
403 -- Authorization Failure
405 -- Invalid Request Method
500 -- Internal Server Error
In the case of any 4XX codes being returned please reference the errorMessage and errorFields response fields to better understand the reason(s).
|errorMessage||List of detailed errors, will contain one to several depending on how many fields are incorrect or missing from the request. Each message will be separated with a <br> tag so the entire value can be URL decoded and then displayed directly to the client/browser to help them understand what to correct.|
|errorFields||Comma Separated Value (CSV) list of specific fields that caused the error(s), the values will match up to the list of request fields in this guide.|
|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 bank information is stored in the profile||bankAccountType||
When performing an operationType of Q (Query) against a profile with stored bank account information, the bank account type will be returned. If no bank account is stored in the profile then this field does not return.
Payment Profiles API – Response Codes
|2||Failed card verification|
|3||Secure connection required|
|4||Invalid service version|
|5||Invalid merchant id|
|6||Invalid operation type|
|8||Invalid customer code|
|10||Unexpected error – Contact support|
|11||Invalid XML message|
|12||Passcode authentication access lockout|
|13||Passcode authentication failure|
|14||Merchant account closed or disabled|
|15||Customer code to modify does not exist|
|16||Customer code already exists|
|17||Duplicate match on payment information|
|18||No fields to update in modification request|
|19||Customer address/payment information failed data validation|
|20||Invalid payment profile account status|
|22||Order number already completed|
|23||No match found on Status Response lookup|
|24||Duplicate match on billing information|
|25||Velocity identifier not assigned to customer code|
|26||Fail send email message|
|27||Operation not enabled|
|28||Invalid profile group|
|29||Invalid transaction id|
|30||No payment information available|
|31||No access to EFT|
|32||An answer was provided without a question|
|33||No answer was provided|
|34||Configuration settings are incomplete|
|35||Maximum number of credit cards is reached|
|36||No credit card found for customer code and card id|
|37||Credit card new information has no changes|
|38||Date input format must be YYYYMMDDHHMM|
|39||AccountRef parameter must be numeric (18,0)|
|40||Payment profile only card cannot be set to non-default|
|41||Reporting services error|
|42||AccountRef value is already assigned to another customer of this merchant|
|43||Operation failed, this card has already been added to the profile|
|44||Operation failed, no matching card id|
|45||Parameters received outside of hash validation. Partial hash must be enabled|
|46||Failed hash validation|
|47||Operation request has expired|
|48||Missing or invalid return URL|
|49||Redirect request type requires hash validation|