Integration Setup
Marqeta setup
Please be aware
Marqeta setup is only necessary if the simulation APIs are used for testing purposes.
For help with setting up the production environment, please contact Marqeta.
Mambu setup
Create Mambu user
Log in to your Mambu environment, create a user with API access for MPO and grant necessary permissions or a role. Copy the username and password.
Create a current account
Create a Current Account product and enable the Allow Technical Overdrafts option for it.
Create transaction channels
Create the following transaction channels in Mambu. You can use the naming suggested below or you can choose your own naming convention for Transaction Channels.
Marqeta.authorization.clearing.{currency}
Marqeta.authorization.clearing.atm.withdrawal.{currency}
Marqeta.refund.{currency}
Marqeta.original.credit.authorization.{currency}
Marqeta.refund.authorization.clearing.{currency}
Marqeta.authorization.clearing.quasi.cash.{currency}
Marqeta.authorization.clearing.cashback.{currency}
Marqeta.pindebit.{currency}
Marqeta.pindebit.cashback.{currency}
Marqeta.pindebit.ATM.Withdrawal.{currency}
Marqeta.pindebit.authorization.clearing.{currency}
Marqeta.pindebit.reversal.{currency}
Marqeta.authorization.clearing.representment.{currency}
Marqeta.original.credit.auth.plus.capture.{currency}
Marqeta.authorization.clearing.chargeback.{currency}
Marqeta.authorization.clearing.chargeback.completed.{currency}
Marqeta.pindebit.chargeback.{currency}
Marqeta.pindebit.chargeback.completed.{currency}
Marqeta.account.funding.authorization.clearing.{currency}
Marqeta.pindebit.refund.reversal.{currency}
Marqeta.original.credit.auth_plus_capture.reversal.{currency}
Marqeta.authorization.clearing.chargeback.reversal.{currency}
Marqeta.pindebit.chargeback.reversal.{currency}
Each transaction channel should have its own linked general ledger (GL) account. Refer to the creating your chart of accounts article in our User Guide for more information on this process. The GL account type must be Asset, as it will overwrite the Transaction Source GL configured at the deposit product level.
Transaction Channels can be configured for multiple currencies. The .{currency}
suffix appended to the transaction channel ID
allows the connector to handle card transactions in multiple currencies.
Example
Organization allows posting card transactions in two different currencies: EUR
and GBP
. Two sets of Transaction channels should be created as follows:
Transaction channels for EUR
Transaction channel name - EUR | Transaction channel ID - EUR |
---|---|
Marqeta.authorization.clearing.EUR | auth.clearing.EUR |
Marqeta.authorization.clearing.atm.withdrawal.EUR | auth.clearing.atm.withdrawal.EUR |
Marqeta.refund.EUR | refund.EUR |
Marqeta.original.credit.authorization.EUR | original.credit.auth.EUR |
Marqeta.refund.authorization.clearing.EUR | refund.auth.clearing.EUR |
Marqeta.authorization.clearing.quasi.cash.EUR | auth.clearing.quasi.cash.EUR |
Marqeta.authorization.clearing.cashback.EUR | auth.clearing.cashback.EUR |
Marqeta.pindebit.EUR | pindebit.EUR |
Marqeta.pindebit.cashback.EUR | pindebit.cashback.EUR |
Marqeta.pindebit.ATM.Withdrawal.EUR | pindebit.atm.withdrawal.EUR |
Marqeta.pindebit.authorization.clearing.EUR | pindebit.auth.clr.EUR |
Marqeta authorization.clearing.representment.EUR | auth.clr.representment.EUR |
Marqeta.original.credit.auth.plus.capture.EUR | org.credit.auth.cap.EUR |
Marqeta.pindebit.reversal.EUR | pindebit.rvs.EUR |
Marqeta.authorization.clearing.chargeback.EUR | auth.clr.chrg.EUR |
Marqeta.authorization.clearing.chargeback.completed.EUR | auth.clr.chrg.compl.EUR |
Marqeta.pindebit.chargeback.EUR | pindebit.chrg.EUR |
Marqeta.pindebit.chargeback.completed.EUR | pindebit.chrg.compl.EUR |
Marqeta.account.funding.authorization.clearing.EUR | acc.fund.auth.clr.EUR |
Marqeta.pindebit.refund.reversal.EUR | pindebit.refund.rvs.EUR |
Marqeta.original.credit.auth_plus_capture.reversal.EUR | org.credit.auth.cap.rvs.EUR |
Marqeta.authorization.clearing.chargeback.reversal.EUR | auth.clr.chrg.rvs.EUR |
Marqeta.pindebit.chargeback.reversal.EUR | pindebit.chrg.rvs.EUR |
Transaction Channels for GBP
Transaction channel name - GBP | Transaction channel ID - GBP |
---|---|
Marqeta.authorization.clearing.GBP | auth.clearing.GBP |
Marqeta.authorization.clearing.atm.withdrawal.GBP | auth.clearing.atm.withdrawal.GBP |
Marqeta.refund.GBP | refund.GBP |
Marqeta.original.credit.authorization.GBP | original.credit.auth.GBP |
Marqeta.refund.authorization.clearing.GBP | refund.auth.clearing.GBP |
Marqeta.authorization.clearing.quasi.cash.GBP | auth.clearing.quasi.cash.GBP |
Marqeta.authorization.clearing.cashback.GBP | auth.clearing.cashback.GBP |
Marqeta.pindebit.GBP | pindebit.GBP |
Marqeta.pindebit.cashback.GBP | pindebit.cashback.GBP |
Marqeta.pindebit.ATM.Withdrawal.GBP | pindebit.atm.withdrawal.GBP |
Marqeta.pindebit.authorization.clearing.GBP | pindebit.auth.clr.GBP |
Marqeta authorization.clearing.representment.GBP | auth.clr.representment.GBP |
Marqeta.original.credit.auth.plus.capture.GBP | org.credit.auth.cap.GBP |
Marqeta.pindebit.reversal.GBP | pindebit.rvs.GBP |
Marqeta.authorization.clearing.chargeback.GBP | auth.clr.chrg.GBP |
Marqeta.authorization.clearing.chargeback.completed.GBP | auth.clr.chrg.compl.GBP |
Marqeta.pindebit.chargeback.GBP | pindebit.chrg.GBP |
Marqeta.pindebit.chargeback.completed.GBP | pindebit.chrg.compl.GBP |
Marqeta.account.funding.authorization.clearing.GBP | acc.fund.auth.clr.GBP |
Marqeta.pindebit.refund.reversal.GBP | pindebit.refund.rvs.GBP |
Marqeta.original.credit.auth_plus_capture.reversal.GBP | org.credit.auth.cap.rvs.GBP |
Marqeta.authorization.clearing.chargeback.reversal.GBP | auth.clr.chrg.rvs.GBP |
Marqeta.pindebit.chargeback.reversal.GBP | pindebit.chrg.rvs.GBP |
In the connector setup, the transaction channels should be saved without the .{currency}
suffix. This suffix is dynamically added to the transaction channel ID by the connector, based on the currency received in the payload. This means that even if you have, for example, four transactions in Mambu to represent four different currencies, there will only be one matching transaction channel in the connector itself.
"transactionChannels": {
"authorizationClearingAtmWithdrawalChannel": "auth.clearing.atm.withdrawal",
"refundChannel": "refund",
"authorizationClearingChannel": "auth.clearing",
"originalCreditAuthorizationChannel": "original.credit.auth",
"refundAuthorizationClearingChannel": "refund.auth.clearing",
"authorizationClearingQuasiCashChannel": "auth.clearing.quasi.cash",
"authorizationClearingCashbackChannel": "auth.clearing.cashback",
"pindebitChannel": "pindebit",
"pindebitAtmWithdrawalChannel": "pindebit.atm.withdrawal",
"pindebitCashbackChannel": "pindebit.cashback",
"pindebitAuthorizationClearingChannel": "pindebit.auth.clr",
"pindebitReversalChannel": "pindebit.rvs",
"pindebitRefundChannel": "pindebit.refund",
"clearingRepresentmentChannel": "auth.clr.representment",
"originalCreditAuthCaptureChannel": "org.credit.auth.cap",
"authClearingChargebackChannel": "auth.clr.chrg",
"authClearingChargebackCompletedChannel": "auth.clr.chrg.compl",
"pindebitChargebackChannel": "pindebit.chrg",
"pindebitChargebackCompletedChannel": "pindebit.chrg.compl",
"accountFundingAuthClearingChannel": "acc.fund.auth.clr",
"pindebitRefundReversalChannel": "pindebit.refund.rvs",
"originalCreditAuthPlusCaptureReversalChannel": "org.credit.auth.cap.rvs",
"authorizationClearingChargebackReversalChannel": "auth.clr.chrg.rvs",
"pindebitChargebackReversalChannel": "pindebit.chrg.rvs"
}
Based on the type of the Marqeta event, the currency_code
parameter is mapped dynamically.
For DBIT financial transactions the currency_code
is read from the gpa_order
object:
data.financialTransaction.transactionChannelId = data.mambuConfig.transactionChannels.authorizationClearingChannel + "." + data.transaction.gpa_order.currency_code
For CRDT financial transactions the currency_code
is read from the transaction
object:
data.financialTransaction.transactionChannelId = data.mambuConfig.transactionChannels.refundChannel + "." + data.transaction.currency_code;
Create custom fields
Follow these steps:
- Add a new custom field set in Mambu.
- Under the newly created custom field set, add the following custom fields.
Please be aware
When adding the custom fields, you should only select the transaction channels created specifically for this connector in the Usage section.
The Custom Fields that need to be created and their type are in the table below.
Custom Field Name | Type |
---|---|
Issuer Bin | Free Text |
Settlement Date | Date |
Transaction ID | Free Text |
Customer ID | Free Text |
Original amount | Number |
Original currency | Free Text |
Conversion rate | Number |
Batch number | Free Text |
Issue fee | Number |
Switch fee | Number |
Pindebit association fee | Number |
Acquirer fee | Number |
Interchange fee | Number |
Currency conversion cardholder fee | Number |
Currency conversion issuer fee | Number |
Cross border issuer fee | Number |
MPO connector setup
Import the connector
Create an API key
You will need to create an API key and add it to the JIT Actionable and Informative Notifications Receiver processes.
API Key:
Add the key to the process:
Run the setup process
Open the Setup & Config
folder and run the Connector setup process (Mambu + notifications)
Please be aware
The Transaction channel IDs should be added without the .{currency}
suffix, as stated above in Mambu Setup. To toggle the custom fields, set the value of parameter enableCustomInformation
to true/false.
Required parameters:
{
"enableCustomInformation": "<boolean, switch on/off custom transaction fields>",
"mambuUrl": "<Mambu Tenant Url>",
"mambuUser": "<Mambu Api user name>",
"mambuPassword": "<user password>",
//Mambu transaction channels
"originalCreditAuthorizationChannel": "<original Credit Authorization Channel id>",
"refundAuthorizationClearingChannel": "<refund Authorization Clearing Channel id>",
"authorizationClearingAtmWithdrawalChannel": "<authorization Clearing Atm Withdrawal Channel id>",
"authorizationClearingCashbackChannel": "<authorization Clearing Cashback Channel id>",
"authorizationClearingChannel": "<authorization Clearing Channel id>",
"authorizationClearingQuasiCashChannel": "<authorization Clearing Quasi Cash Channel id>",
"refundChannel": "<refund Channel id>",
"pindebitChannel": "<pindebit Channel id>",
"pindebitAtmWithdrawalChannel": "<pindebit atm withdrawal Channel id>",
"pindebitCashbackChannel": "<pindebit cashback Channel id>",
"pindebitAuthorizationClearingChannel": "<pindebit authorization clearing Channel id>",
"pindebitReversalChannel" : "<pindebit reversal Channel id>",
"clearingRepresentmentChannel": "<authorization clearing representment Channel>",
"originalCreditAuthCaptureChannel": "<original credit authorizatin plus capture Channel>",
"authClearingChargebackChannel": "<authorization clearing chargeback Channel >",
"authClearingChargebackCompletedChannel": "<authorization clearing chargeback completed Channel >",
"pindebitChargebackChannel": "<pindebit chargeback Channel >",
"pindebitChargebackCompletedChannel": "<pindebit chargeback completed Channel >",
"accountFundingAuthClearingChannel": "<account funding authorization clearing Channel>",
"pindebitRefundReversalChannel" : "<pindebit refund reversal Channel>",
"originalCreditAuthPlusCaptureReversalChannel" : "<original credit auth plus capture reversal Channel>",
"authorizationClearingChargebackReversalChannel": "<authorization clearing chargeback reversal Channel>",
"pindebitChargebackReversalChannel": "<pindebit chargeback reversal Channel>"
//Mambu custom fields
"marqetaAquirerFeeCF": "<acquirer fee custom field id>",
"marqetaBatchNumberCF": "<batch number custom field id>",
"marqetaConversionRateCF": "<conversion rate custom field id>",
"marqetaCrossBorderIssuerFeeCF": "<cross border issuer fee custom field id>",
"marqetaCurConvCardholderFeeCF": "<currency conversion cardholder fee custom field id>",
"marqetaCurConvIssuerFeeCF": "<currency conversion issuer fee custom field id>",
"marqetaCustomFieldSetId": "<Mambu custom field set id>",
"marqetaInterchangeFeeCF": "<interchange fee custom field id>",
"marqetaIssuerBinCF": "<issuer BIN custom field id>",
"marqetaIssuerFeeCF": "<issuer fee custom field id>",
"marqetaMambuCustomerIdCF": "<customer id custom field id>",
"marqetaOriginalAmountCF": "<original amount custom field id>",
"marqetaOriginalCurrencyCF": "<original currency custom field id>",
"marqetaPinDebitAssocFeeCF": "<PIN Debit association custom field id>",
"marqetaSettlementDateCF": "<settlement date custom field id>",
"marqetaSwitchFeeCF": "<switch fee custom field id>",
"marqetaVisaTransactionIdCF": "<VISA transaction Id custom field id>",
//Notifications config data
"mambuTaskAssignedUser": "<Mambu task assigned user encodedKey>",
"clearingNotifications": "<true/false>",
"channel": "<task/zenDesk>",
"webhookUrl": "<webhook Url for notifications>",
"zenDeskApiKey": "<ZenDesk ApiKey>",
"zenDeskGroupId": "<ZenDesk GroupId>",
"zenDeskLogin": "<ZenDesk Login>",
"zenDeskSubdomain": "<ZenDesk Subdomain>"
}
API gateway setup
You have two options for calling the JIT Actionable Receiver and the JIT Informative Notifications Receiver MPO processes:
- Creating your own API Gateways.
- Using the connector’s AWS API Gateways with Lambda functions.
Creating your own API gateways
You need to use the following details when calling the JIT Actionable Receiver and the JIT Informative Notifications Receiver processes via your own API Gateways:
- The HTTP method used for calling the process is POST.
- Call URL:
{YOUR_MPO_ENVIRONMENT}-syncapi.mambuonline.com/api/JSON/{LOGIN}/{TIMESTAMP}{SIGNATURE}
- {LOGIN}: Parameter has the value of the Login API Key created in MPO.
- {TIMESTAMP}: The current unix timestamp.
- {SIGNATURE}: Signatures are used to authenticate requests and are created based on time, API Key Secret and request data.
More information about signing your requests to MPO can be found in our MPO Sync API support article.
The payload to include with the request will look like this:
{
"ops": [
{
"company_id": "string - ID of the company on which the connector is installed on MPO",
"obj_id": "string - ID of the targeted process",
"type": "create",
"obj": "task",
"data": "object - The payload expected by the MPO process"
}
]
}
Parameter | Type | Description | Required |
---|---|---|---|
ops | JSON Object | A list encapsulating all the tasks to run on MPO. | Yes |
ops[].type | string | The task type. | Yes |
ops[].obj | string | An object type to run the tasks on. | No |
ops[].obj_id | string | The ID of the object. | No |
ops[].company_id | string | The ID of the company. | Yes |
The MPO platform will only respond with a 200
HTTP code, so your API Gateway must be capable of mapping any error returned by MPO as a JSON body to the 402
HTTP code when responding to the Marqeta system.
JSON payload examples expected as input by the MPO processes JIT Actionable Receiver and JIT Informative Notification Receiver can be found in the GitLab repository provided when you purchase this connector or from your integration consultant.
More information about jit_funding
messages can be found in the Marqeta documentation.
A. API Gateway requirements for the JIT Actionable Receiver
JIT Actionable Gateway will send any actionable messages received from the Marqeta platform to the JIT Actionable Receiver MPO process.
JIT Actionable Gateway will programmatically return the jit_funding
object received from the JIT Actionable Receiver, to approve or deny the funding request.
A complete JIT Funding response includes the following elements:
- The appropriate HTTP response code (
200 OK
or402 Payment Required
). - The
jit_funding
object as is received from the JIT Actionable Receiver.
JIT Actionable Receiver will respond to the JIT Actionable Gateway with the following elements:
- For approved requests:
{
"jit_funding": {
"token": "**YOUR JIT FUNDING REQUEST TOKEN**",
"method": "pgfs.authorization",
"user_token": "**YOUR USER TOKEN**",
"memo": "Approved",
"amount": 10.00
}
}
- For rejected requests:
{
"jit_funding": {
"token": "**YOUR JIT FUNDING REQUEST TOKEN**",
"method": "pgfs.authorization",
"user_token": "**YOUR USER TOKEN**",
"amount": 10.00,
"decline_reason": "decline_reason",
"tags": "Mambu error reason"
}
}
More information about the jit_funding
responses can be found here.
B. API Gateway requirements for the JIT Informative Notifications Receiver
JIT Informative Notifications Gateway will send to the JIT Informative Notifications Receiver MPO process the transactions received from the Marqeta platform. The events are received in batches as webhook notifications.
JIT Informative Notifications Gateway will only respond to the Marqeta platform with the appropriate HTTP response code (200 OK
or 402 Payment Required
).
JIT Informative Notifications Receiver will respond to the JIT Informative Notifications Gateway with the following elements:
- For accepted requests:
{
"message": "Batch accepted!",
"statusCode": 200
}
- For rejected requests:
{
"message": "Batch rejected!",
"statusCode": 402
}
If the JIT Informative Notifications Gateway does not respond with a 200
HTTP response code, the Marqeta platform will try to resend the notification.
Using our AWS API gateways
JIT Actionable Receiver entry point requires the creation of an API gateway with 2 Lambda functions as follows:
- 1 API gateway which handles the actionable events from Marqeta;
- 1 Lambda function for the Basic Authentication;
- 1 Lambda function used for triggering JIT Actionable Receiver and sending back the response to Marqeta;
JIT Informative Receiver entry point requires the creation of an API gateway with 2 Lambda functions as follows:
- 1 API gateway which handles the informative events from Marqeta;
- 1 Lambda function for the Basic Authentication;
- 1 Lambda function used for triggering the JIT Informative Receiver and for the Marqeta Digital Signature check
Please contact your Integration Consultant to assist you with the AWS configuration for the two API Gateways and their corresponding lambda functions.