Validate a credit

Validate a credit before execution

curl --request POST \
  --url https://api.examplebank.com/meridian/v1/credits/validate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transactionId": "mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27",
  "amount": {
    "value": "1500.00",
    "currency": "PHP"
  },
  "recipient": {
    "account": {
      "accountNumber": "001234567890"
    },
    "firstName": "Maria",
    "lastName": "Santos"
  },
  "sender": {
    "firstName": "Juan",
    "lastName": "Cruz",
    "dateOfBirth": "1990-01-15",
    "address": {
      "addressLines": [
        "123 Test Street"
      ],
      "city": "Taguig",
      "stateProvince": "Metro Manila",
      "postalCode": "1634",
      "country": "PH"
    }
  },
  "metadata": {
    "reference": "R9x8k2m4p6w1c3v5b7n9q0z2"
  }
}
'

import requests

url = "https://api.examplebank.com/meridian/v1/credits/validate"

payload = {
    "transactionId": "mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27",
    "amount": {
        "value": "1500.00",
        "currency": "PHP"
    },
    "recipient": {
        "account": { "accountNumber": "001234567890" },
        "firstName": "Maria",
        "lastName": "Santos"
    },
    "sender": {
        "firstName": "Juan",
        "lastName": "Cruz",
        "dateOfBirth": "1990-01-15",
        "address": {
            "addressLines": ["123 Test Street"],
            "city": "Taguig",
            "stateProvince": "Metro Manila",
            "postalCode": "1634",
            "country": "PH"
        }
    },
    "metadata": { "reference": "R9x8k2m4p6w1c3v5b7n9q0z2" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    transactionId: 'mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27',
    amount: {value: '1500.00', currency: 'PHP'},
    recipient: {
      account: {accountNumber: '001234567890'},
      firstName: 'Maria',
      lastName: 'Santos'
    },
    sender: {
      firstName: 'Juan',
      lastName: 'Cruz',
      dateOfBirth: '1990-01-15',
      address: {
        addressLines: ['123 Test Street'],
        city: 'Taguig',
        stateProvince: 'Metro Manila',
        postalCode: '1634',
        country: 'PH'
      }
    },
    metadata: {reference: 'R9x8k2m4p6w1c3v5b7n9q0z2'}
  })
};

fetch('https://api.examplebank.com/meridian/v1/credits/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.examplebank.com/meridian/v1/credits/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'transactionId' => 'mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27',
    'amount' => [
        'value' => '1500.00',
        'currency' => 'PHP'
    ],
    'recipient' => [
        'account' => [
                'accountNumber' => '001234567890'
        ],
        'firstName' => 'Maria',
        'lastName' => 'Santos'
    ],
    'sender' => [
        'firstName' => 'Juan',
        'lastName' => 'Cruz',
        'dateOfBirth' => '1990-01-15',
        'address' => [
                'addressLines' => [
                                '123 Test Street'
                ],
                'city' => 'Taguig',
                'stateProvince' => 'Metro Manila',
                'postalCode' => '1634',
                'country' => 'PH'
        ]
    ],
    'metadata' => [
        'reference' => 'R9x8k2m4p6w1c3v5b7n9q0z2'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.examplebank.com/meridian/v1/credits/validate"

	payload := strings.NewReader("{\n  \"transactionId\": \"mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27\",\n  \"amount\": {\n    \"value\": \"1500.00\",\n    \"currency\": \"PHP\"\n  },\n  \"recipient\": {\n    \"account\": {\n      \"accountNumber\": \"001234567890\"\n    },\n    \"firstName\": \"Maria\",\n    \"lastName\": \"Santos\"\n  },\n  \"sender\": {\n    \"firstName\": \"Juan\",\n    \"lastName\": \"Cruz\",\n    \"dateOfBirth\": \"1990-01-15\",\n    \"address\": {\n      \"addressLines\": [\n        \"123 Test Street\"\n      ],\n      \"city\": \"Taguig\",\n      \"stateProvince\": \"Metro Manila\",\n      \"postalCode\": \"1634\",\n      \"country\": \"PH\"\n    }\n  },\n  \"metadata\": {\n    \"reference\": \"R9x8k2m4p6w1c3v5b7n9q0z2\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.examplebank.com/meridian/v1/credits/validate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"transactionId\": \"mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27\",\n  \"amount\": {\n    \"value\": \"1500.00\",\n    \"currency\": \"PHP\"\n  },\n  \"recipient\": {\n    \"account\": {\n      \"accountNumber\": \"001234567890\"\n    },\n    \"firstName\": \"Maria\",\n    \"lastName\": \"Santos\"\n  },\n  \"sender\": {\n    \"firstName\": \"Juan\",\n    \"lastName\": \"Cruz\",\n    \"dateOfBirth\": \"1990-01-15\",\n    \"address\": {\n      \"addressLines\": [\n        \"123 Test Street\"\n      ],\n      \"city\": \"Taguig\",\n      \"stateProvince\": \"Metro Manila\",\n      \"postalCode\": \"1634\",\n      \"country\": \"PH\"\n    }\n  },\n  \"metadata\": {\n    \"reference\": \"R9x8k2m4p6w1c3v5b7n9q0z2\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.examplebank.com/meridian/v1/credits/validate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"transactionId\": \"mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27\",\n  \"amount\": {\n    \"value\": \"1500.00\",\n    \"currency\": \"PHP\"\n  },\n  \"recipient\": {\n    \"account\": {\n      \"accountNumber\": \"001234567890\"\n    },\n    \"firstName\": \"Maria\",\n    \"lastName\": \"Santos\"\n  },\n  \"sender\": {\n    \"firstName\": \"Juan\",\n    \"lastName\": \"Cruz\",\n    \"dateOfBirth\": \"1990-01-15\",\n    \"address\": {\n      \"addressLines\": [\n        \"123 Test Street\"\n      ],\n      \"city\": \"Taguig\",\n      \"stateProvince\": \"Metro Manila\",\n      \"postalCode\": \"1634\",\n      \"country\": \"PH\"\n    }\n  },\n  \"metadata\": {\n    \"reference\": \"R9x8k2m4p6w1c3v5b7n9q0z2\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "transactionId": "mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27",
  "status": "VALIDATED"
}

POST

credits

validate

Validate a credit before execution

curl --request POST \
  --url https://api.examplebank.com/meridian/v1/credits/validate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transactionId": "mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27",
  "amount": {
    "value": "1500.00",
    "currency": "PHP"
  },
  "recipient": {
    "account": {
      "accountNumber": "001234567890"
    },
    "firstName": "Maria",
    "lastName": "Santos"
  },
  "sender": {
    "firstName": "Juan",
    "lastName": "Cruz",
    "dateOfBirth": "1990-01-15",
    "address": {
      "addressLines": [
        "123 Test Street"
      ],
      "city": "Taguig",
      "stateProvince": "Metro Manila",
      "postalCode": "1634",
      "country": "PH"
    }
  },
  "metadata": {
    "reference": "R9x8k2m4p6w1c3v5b7n9q0z2"
  }
}
'

import requests

url = "https://api.examplebank.com/meridian/v1/credits/validate"

payload = {
    "transactionId": "mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27",
    "amount": {
        "value": "1500.00",
        "currency": "PHP"
    },
    "recipient": {
        "account": { "accountNumber": "001234567890" },
        "firstName": "Maria",
        "lastName": "Santos"
    },
    "sender": {
        "firstName": "Juan",
        "lastName": "Cruz",
        "dateOfBirth": "1990-01-15",
        "address": {
            "addressLines": ["123 Test Street"],
            "city": "Taguig",
            "stateProvince": "Metro Manila",
            "postalCode": "1634",
            "country": "PH"
        }
    },
    "metadata": { "reference": "R9x8k2m4p6w1c3v5b7n9q0z2" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    transactionId: 'mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27',
    amount: {value: '1500.00', currency: 'PHP'},
    recipient: {
      account: {accountNumber: '001234567890'},
      firstName: 'Maria',
      lastName: 'Santos'
    },
    sender: {
      firstName: 'Juan',
      lastName: 'Cruz',
      dateOfBirth: '1990-01-15',
      address: {
        addressLines: ['123 Test Street'],
        city: 'Taguig',
        stateProvince: 'Metro Manila',
        postalCode: '1634',
        country: 'PH'
      }
    },
    metadata: {reference: 'R9x8k2m4p6w1c3v5b7n9q0z2'}
  })
};

fetch('https://api.examplebank.com/meridian/v1/credits/validate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.examplebank.com/meridian/v1/credits/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'transactionId' => 'mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27',
    'amount' => [
        'value' => '1500.00',
        'currency' => 'PHP'
    ],
    'recipient' => [
        'account' => [
                'accountNumber' => '001234567890'
        ],
        'firstName' => 'Maria',
        'lastName' => 'Santos'
    ],
    'sender' => [
        'firstName' => 'Juan',
        'lastName' => 'Cruz',
        'dateOfBirth' => '1990-01-15',
        'address' => [
                'addressLines' => [
                                '123 Test Street'
                ],
                'city' => 'Taguig',
                'stateProvince' => 'Metro Manila',
                'postalCode' => '1634',
                'country' => 'PH'
        ]
    ],
    'metadata' => [
        'reference' => 'R9x8k2m4p6w1c3v5b7n9q0z2'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.examplebank.com/meridian/v1/credits/validate"

	payload := strings.NewReader("{\n  \"transactionId\": \"mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27\",\n  \"amount\": {\n    \"value\": \"1500.00\",\n    \"currency\": \"PHP\"\n  },\n  \"recipient\": {\n    \"account\": {\n      \"accountNumber\": \"001234567890\"\n    },\n    \"firstName\": \"Maria\",\n    \"lastName\": \"Santos\"\n  },\n  \"sender\": {\n    \"firstName\": \"Juan\",\n    \"lastName\": \"Cruz\",\n    \"dateOfBirth\": \"1990-01-15\",\n    \"address\": {\n      \"addressLines\": [\n        \"123 Test Street\"\n      ],\n      \"city\": \"Taguig\",\n      \"stateProvince\": \"Metro Manila\",\n      \"postalCode\": \"1634\",\n      \"country\": \"PH\"\n    }\n  },\n  \"metadata\": {\n    \"reference\": \"R9x8k2m4p6w1c3v5b7n9q0z2\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.examplebank.com/meridian/v1/credits/validate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"transactionId\": \"mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27\",\n  \"amount\": {\n    \"value\": \"1500.00\",\n    \"currency\": \"PHP\"\n  },\n  \"recipient\": {\n    \"account\": {\n      \"accountNumber\": \"001234567890\"\n    },\n    \"firstName\": \"Maria\",\n    \"lastName\": \"Santos\"\n  },\n  \"sender\": {\n    \"firstName\": \"Juan\",\n    \"lastName\": \"Cruz\",\n    \"dateOfBirth\": \"1990-01-15\",\n    \"address\": {\n      \"addressLines\": [\n        \"123 Test Street\"\n      ],\n      \"city\": \"Taguig\",\n      \"stateProvince\": \"Metro Manila\",\n      \"postalCode\": \"1634\",\n      \"country\": \"PH\"\n    }\n  },\n  \"metadata\": {\n    \"reference\": \"R9x8k2m4p6w1c3v5b7n9q0z2\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.examplebank.com/meridian/v1/credits/validate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"transactionId\": \"mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27\",\n  \"amount\": {\n    \"value\": \"1500.00\",\n    \"currency\": \"PHP\"\n  },\n  \"recipient\": {\n    \"account\": {\n      \"accountNumber\": \"001234567890\"\n    },\n    \"firstName\": \"Maria\",\n    \"lastName\": \"Santos\"\n  },\n  \"sender\": {\n    \"firstName\": \"Juan\",\n    \"lastName\": \"Cruz\",\n    \"dateOfBirth\": \"1990-01-15\",\n    \"address\": {\n      \"addressLines\": [\n        \"123 Test Street\"\n      ],\n      \"city\": \"Taguig\",\n      \"stateProvince\": \"Metro Manila\",\n      \"postalCode\": \"1634\",\n      \"country\": \"PH\"\n    }\n  },\n  \"metadata\": {\n    \"reference\": \"R9x8k2m4p6w1c3v5b7n9q0z2\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "transactionId": "mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27",
  "status": "VALIDATED"
}

Authorizations

Authorization

string

header

required

Assume OAuth 2.0 client credentials issued by the bank, presented as a bearer token. Meridian can adapt to the bank's preferred authentication scheme during onboarding.

Body

application/json

A credit (payout) instruction from Meridian to the bank.

transactionId

string

required

Meridian's unique identifier for this credit and the idempotency key. Stable across retries and across the validate/commit/status lifecycle of one transaction.

Maximum string length: 64

Example:

"mrdn-9f2c1e4a-71bd-4c5e-a2f3-8d6b0c9e1a27"

amount

object

required

Show child attributes

recipient

object

required

The customer being credited at the home bank.

Show child attributes

sender

object

Originator of the funds (KYC data). Included on commit for compliance screening. Field-level availability is confirmed during onboarding, and some corridors add further compliance fields (for example the sender's relationship to the recipient, or source of income) that Meridian agrees with the bank at that time.

Show child attributes

purpose

string

Human-readable purpose / remittance information for the transfer.

Maximum string length: 140

Example:

"Wallet withdrawal payout"

metadata

object

Additional key/value context supplied by Meridian (e.g. a customer-facing reference to print on statements). Banks should persist and echo these where their core allows, but must not require fields beyond those agreed at onboarding.

Show child attributes

Response

Validation outcome (both eligible and ineligible accounts return 200).

Outcome of a validate, commit, or status call. One shape for all three.

transactionId

string

required

Echo of Meridian's transaction identifier.

status

enum<string>

required

Transaction state machine:

RECEIVED — registered; nothing checked and nothing moved
VALIDATED — the recipient account passed eligibility checks
PROCESSING — money movement is underway
COMPLETED — terminal; the funds reached the recipient
FAILED — terminal; the credit will not be delivered
UNKNOWN — outcome not yet determinable, for example a timeout in your core system or an unreachable downstream rail; not terminal

Status moves only forward through that order, though skipping steps is fine, and terminal statuses must never change once reported. UNKNOWN is exempt from the ordering and may be followed by any status. Prefer it over guessing FAILED, since a terminal status can never be walked back.

Available options:

RECEIVED,

VALIDATED,

PROCESSING,

COMPLETED,

FAILED,

UNKNOWN

bankReference

string

The bank's own reference for the transfer, if one exists. Meridian stores this for reconciliation and support. Include it on every response after commit.

Maximum string length: 64

errorCode

string

Machine-readable failure code. Required whenever status is FAILED. Use a stable, documented set; Meridian maps these to customer-facing outcomes. Recommended baseline:

ACCOUNT_NOT_FOUND
ACCOUNT_INACTIVE
NAME_MISMATCH
LIMIT_EXCEEDED
INVALID_AMOUNT
COMPLIANCE_REJECTED
INSUFFICIENT_FUNDS (sponsored account)
DUPLICATE_TRANSACTION
BANK_SYSTEM_ERROR

errorMessage

string

Human-readable detail for the failure. Not shown to customers verbatim.

Maximum string length: 500

completedAt

string<date-time>

RFC 3339 timestamp when the credit reached a final status.

⌘I

Integration Types

Credit API Example

Validate a credit

Authorizations

Body

Response