Integration Setup

1. Marqeta Setup

For complete assistance with setting up the production environment, please contact Marqeta.

2. Mambu Setup

1. Log in to Mambu

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.

2. Create a Current Account

Create a Current Account product and enable the Allow Technical Overdrafts option for it.

3. Transaction channels

Create the following transaction channels in Mambu:

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

Each transaction channel should have its own General Ledger (GL) account linked. Documentation on GL accounts creation here. The GL account type must be Asset, as it will overwrite the Transaction Source GL configured at the deposit product level.

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 Channels for 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"
        }

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;

4. 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.

The Custom Fields that need to be created and their type are in the table below.

3. MPO Connector Setup

1. Import the archive containing the connector to MPO

2. Create an API Key and add it to the JIT Actionable and Informative Notifications Receiver processes.

API Key:

Add the key to the process:

3. Open the Setup & Config folder and run the Connector setup process (Mambu + notifications)

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 >",
    //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>"
}

4. API Gateway Setup

There are two ways to call the JIT Actionable Receiver and the JIT Informative Notifications Receiver MPO processes:

1. Creating your own API Gateways.
2. Using the connector’s AWS API Gateways with Lambda functions.

4.1. 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 regarding 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"
    }
  ]
}

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 or 402 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.

4.2. Using our AWS API Gateways

To call the JIT Actionable Receiver and JIT Informative Notifications Receiver processes using the connector’s AWS API Gateways, the following setup is required.

Create two different API Gateways as follows:

1. An AWS API Gateway endpoint and Lambda functions through which the Marqeta JIT Funding Request is sent to the JIT Actionable Receiver process in MPO.
2. An AWS API Gateway endpoint and Lambda functions through which the Marqeta JIT Funding Notification is sent to the JIT Informative Notifications Receiver process in MPO.

A. API Gateway for JIT Actionable Receiver

JIT Actionable Receiver entry point requires the creation of an API gateway with 2 Lambda functions as follows:

• An API gateway that handles the actionable events from Marqeta;
  
• A Lambda function for the Basic Authentication;
     - authenticates the event received from the Marqeta.
     - requires storing the Basic Authentication Token as secret key in AWS Secrets.
  
• A Lambda function that triggers JIT Actionable Receiver and sends back the response to Marqeta;
  

First of all, you will need to store the secret key that will be used later in the configuration of the Lambda function that handles request authentication.

1. AWS Secret setup for Basic Authentication

The secret key to be stored in AWS for the basic authentication is the token resulting from the base64 encoding the username and password used by Marqeta to authenticate the requests. You can use this link to obtain the Basic Auth token by encoding the provided username and password.
For example:

• Encode: “cardsUser:cardsPassword”
  
• Token: “Y2FyZHNVc2VyOmNhcmRzUGFzc3dvcmQ=”
  

1.1. Access the AWS Secrets Manager service:

1.2. Create a new secret key and provide an identifiable name for the it (Eg: MarqetaBasicAuthToken)

Please note that “value1” from the screenshot above should match the Basic Authentication Token used by Marqeta to authenticate the actionable requests!

In the end, you should have the new secret key stored in AWS.

1.3. Click on the link of the newly created secret key and copy the Secret Name as it will be used later on when setting up the environment variables of the Lambda Function that handles request authentication.

2. Lambda function used for Basic Authentication

2.1. Login to your AWS console and navigate to Services -> Lambda.
2.2. Create a new Lambda function.
2.3. Upload the .zip file authorizationForActionableLambdaFunction.zip that your Integration Consultant will have provided you.

2.4. Access the Configuration menu and update the Environment variables as follows:

Environment variables:

• region : AWS region hosting the Key
• secretName: Secret Name of your the key created in step1

2.5. In the Configuration -> General configuration menu, update the allocated memory of the Lambda function. If you expect many requests to be received, then allocate the default memory 2048 MB.

2.6. Access the Permissions section and add a Role name that has the proper policies set. Additional details will be provided by your Integration Consultant.

3. Lambda function used for triggering the JIT Actionable Receiver and responding to Marqeta

3.1. Login to your AWS console and navigate to Services -> Lambda.
3.2. Create a new Lambda function.
3.3. Upload the .zip file forMarqetaActionableLambdaFunction.zipthat your Integration Consultant will have provided you.

3.4. Access the Configuration menu and update the Environment variables to include the details of JIT Actionable Receiver MPO process.

Environment variables:

• apiLogin: MPO API Key Login of the process to be called
• company_id: MPO company id where the connector is installed
• conv_id: MPO process id (conveyor id) of the process to be called
• secret: MPO API Key Secret of the process to be called
• url: MPO Sync API URL in the following format: {{your-mpo-environment}}-syncapi.mambuonline.com

3.5. In the Configuration -> General configuration menu, update the allocated memory of the Lambda function. If you expect many requests to be received, then allocate the default memory 2048 MB.

3.6. Access the Permissions section and add a Role name that has the proper policies set. Additional details will be provided by your Integration Consultant.

4. API Gateway for JIT Actionable Receiver

4.1. Navigate to Services > API Gateway and create the endpoint path (click on Create API button).

4.2. Open your new API. Go to Resources > Actions and click on Create Resource.

4.3. Create synchronous endpoint by selecting the previously resource created (e.g: /gateway). Click on Actions > Create Method > POST. Select the POST method and add the Lambda function created at step 2 (e.g: marqetaFunction).

4.4. Open the Method Request section of your API Gateway and access the Settings section. For Authorization, slect the Lambda function created at step 2 (Lambda function for Basic Authentication).
Technical note:
If the function is not displayed in the dropdown list, you need finish the API Gateway creation without setting it. Then, you will need to access the Lambda function and set the API Gateway as its trigger. Once you’ve done this, you can return to the API Gateway and select the Lambda function.

In the Request validator field select “Validate query string parameters and headers”.
In the HTTP Request Headers section add HTTP Request Header (e.g: Authorization).

4.5. Select the Integration Request section from API Gateway and add Mapping Templates (e.g: application/json).

{
"headers":
{
"authorization": "$method.request.header.Authorization"
},
"body" : $input.json('$')
}

4.6. Select the Integration Response section and map Marqeta HTTP response codes.

• Approve request -> 200 OK HTTP response code
• Deny request -> 402 Request Failed response code

Lambda ErrorRegex: .*decline_reason.*|.*Task timed out after.*

Mapping Templates: #set($inputRoot = $input.path('$.errorMessage')) $inputRoot

4.7. Select the Method Response section from API Gateway and map Marqeta HTTP response code and HTTP response body.

4.8. Select Deploy API from Actions menu.

4.9. Copy the API gateway URL, you will need to add this URL to your Marqeta configuration.

B. API Gateway for JIT Informative Notifications Receiver

JIT Informative Receiver entry point requires the creation of an API gateway with two Lambda functions as follows:

• An API gateway to receive incoming informative events from Marqeta;
  
• a Lambda function for the Basic Authentication;
     - requires storing the Basic Authentication Token as secret key in AWS Secrets.
  
• a Lambda function for triggering the JIT Informative Receiver and for the Marqeta Digital Signature check;
     - requires a secret key to be stored in AWS Secrets - used in the digital signature calculation algorithm;
  

First of all, you will need to store the secret keys that will be later on used in the configuration of the Lambda functions.

1. AWS Secret setup for Basic Authentication

In order to create a new secret key, you need to follow the same steps described at point “1. AWS Secret setup for Basic Authentication” from section “A. API Gateway for JIT Actionable Receiver”.

When storing the new Secret use an easily identifiable name (for example: MarqetaBasicAuthorizationInformative), and the token resulting from base64 encoding the new username and password as input value .

Once the Authorization secret key is stored, take note of its Secret Name as it will be used later on when setting up the environment variables of the Authorization Lambda Function.

2. AWS Secret setup for Digital Signature verification

The signature is calculated based on the raw request body and the stored secret key. Marqeta sends this signature as a Header - X-Marqeta-Signature. Signing the request is optional, therefore, the Lambda function does not validate the signature unless it receives it in the request.

In order to setup the Digital Signature verification you need to perform the following Actions:

2.1. First, you need to access the AWS Secrets Manager service:

2.2. Create a new secret key. Provide a suggestive name to your new secret key (Eg: Marqeta_Secret)

Please note that “value1” from the screenshot above should match the secret key used by Marqeta to calculate the digital signature on their end!

In the end, you should have the new secret key stored in AWS.

2.3. Click on the link of the newly created secret key and copy the Secret Name as it will be used later on when setting up the environment variables of the Lambda Function that calculates the Digital Signature:

3. Lambda function used for basic authentication to JIT Informative Receiver

3.1. Follow the same steps described above.
3.2. Upload the .zip file authorizationForInformativeLambdaFunction.zip that your Integration Consultant will be providing you.

3.3. Update the environment variables to contain the details for JIT Informative Receiver MPO process.

Environment variables:

• region : AWS region hosting the Key
• secretName: Secret Name of your new created key
  

3.4. Access the Configuration -> General configuration menu to update the allocated memory of the Lambda function. If you expect many requests to be received, then allocate the default memory 2048 MB.

3.5. Access Permissions section and add a Role name that has the proper policies set. Additional details will be provided by your Integration Consultant.

Once the secret keys and the Lambda functions are done, you need to create the API Gateway that uses the 2 functions.

4. Lambda function used for triggering the JIT Informative Receiver and for the Marqeta Digital Signature check

4.1. Login to your AWS console and navigate to Services -> Lambda.
4.2. Create the Lambda function.
4.3. Upload the .zip file forMarqetaInformativeLambdaFunction.zip that your Integration Consultant will have provided you.

4.4. Update the environment variables to contain the details for JIT Informative Receiver MPO process. Click Save.

Environment variables:

• AWSsecretName: Secret ARN of Marqeta_Secret Key
• LOGIN: MPO API Key Login of the process to be called
• SECRET: MPO API Key Secret of the process to be called
• company_id: MPO company id where the connector is installed
• conv_id: MPO process id (conveyor id) of the process to be called
• region : AWS region hosting Marqeta_Secret Key
• url: MPO Sync API URL in the following format: {{your-mpo-environment}}-syncapi.mambuonline.com

4.5. Access the Configuration -> General configuration menu to update the allocated memory of the Lambda function. If you expect many requests to be received, then allocate the default memory 2048 MB.

4.6. Access the Permissions section and add a Role name that has the proper policies set. Additional details will be provided by your Integration Consultant.

5. API Gateway for JIT Informative Receiver

5.1. Navigate to Services > API Gateway and create the endpoint path (select Create API).

5.2. Open your new API. Go to Resources > Actions and click on Create Resource.

5.3. Create a synchronous endpoint by selecting the previously resource created (e.g: /gateway). Click on Actions - Create Method - POST. Select the POST method and add the Lambda function to the method.

5.4. Select the Method Request section from the API Gateway and in the Settings -> Authorization section, select the Lambda function created at step 3 (Basic authentication Lambda function).
Technical note:
If the function is not displayed in the dropdown list, you need finish the API Gateway creation without setting it. Once the gateway has been created, you will need to access the Lambda function and set the API Gateway as its trigger. Once you’ve done this, you can return to the API Gateway settings page and select the Lambda function.

In the Request validator field select “Validate query string parameters and headers”.
In the HTTP Request Headers section add HTTP Request Header (e.g: Authorization).

5.5. Select Integration Request and add in the Mapping templates section the following template:

##  See http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html
##  This template will pass through all parameters including path, querystring, header, stage variables, and context through to the integration endpoint via the body/payload
#set($allParams = $input.params())
{"original-body":"$util.escapeJavaScript($input.body).replaceAll("\\'","'")",
"body-json" : $input.json('$'),
"params" : {
#foreach($type in $allParams.keySet())
    #set($params = $allParams.get($type))
"$type" : {
    #foreach($paramName in $params.keySet())
    "$paramName" : "$util.escapeJavaScript($params.get($paramName))"
        #if($foreach.hasNext),#end
    #end
}
    #if($foreach.hasNext),#end
#end
},
"stage-variables" : {
#foreach($key in $stageVariables.keySet())
"$key" : "$util.escapeJavaScript($stageVariables.get($key))"
    #if($foreach.hasNext),#end
#end
},
"context" : {
    "account-id" : "$context.identity.accountId",
    "api-id" : "$context.apiId",
    "api-key" : "$context.identity.apiKey",
    "authorizer-principal-id" : "$context.authorizer.principalId",
    "caller" : "$context.identity.caller",
    "cognito-authentication-provider" : "$context.identity.cognitoAuthenticationProvider",
    "cognito-authentication-type" : "$context.identity.cognitoAuthenticationType",
    "cognito-identity-id" : "$context.identity.cognitoIdentityId",
    "cognito-identity-pool-id" : "$context.identity.cognitoIdentityPoolId",
    "http-method" : "$context.httpMethod",
    "stage" : "$context.stage",
    "source-ip" : "$context.identity.sourceIp",
    "user" : "$context.identity.user",
    "user-agent" : "$context.identity.userAgent",
    "user-arn" : "$context.identity.userArn",
    "request-id" : "$context.requestId",
    "resource-id" : "$context.resourceId",
    "resource-path" : "$context.resourcePath"
    }
}

5.6. Select Integration Response section from API Gateway and map Marqeta HTTP response codes.

• Approve batch -> 200 OK HTTP response code

• Reject batch -> 402 Request Failed response code

Lambda ErrorRegex: .*Rejected.*|.*Task timed out after.*

Mapping Templates: #set($inputRoot = $input.path('$')) { }

5.7. Select the Method Response section from the API Gateway and map Marqeta HTTP response code and HTTP response body.

5.8. Select Deploy API from Actions menu.

5.9. Copy the API gateway URL, you will need to add this URL to your Marqeta configuration.