Payments - Create and Confirm Intent

curl --request POST \
  --url https://sandbox.birrpay.io/v2/payments \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'X-Profile-Id: <x-profile-id>' \
  --data '
{
  "amount_details": {
    "currency": "USD",
    "order_amount": 6540
  },
  "payment_method_data": {
    "card": {
      "card_cvc": "123",
      "card_exp_month": "10",
      "card_exp_year": "25",
      "card_holder_name": "joseph Doe",
      "card_number": "4242424242424242"
    }
  },
  "payment_method_subtype": "credit",
  "payment_method_type": "card"
}
'

import requests

url = "https://sandbox.birrpay.io/v2/payments"

payload = {
    "amount_details": {
        "currency": "USD",
        "order_amount": 6540
    },
    "payment_method_data": { "card": {
            "card_cvc": "123",
            "card_exp_month": "10",
            "card_exp_year": "25",
            "card_holder_name": "joseph Doe",
            "card_number": "4242424242424242"
        } },
    "payment_method_subtype": "credit",
    "payment_method_type": "card"
}
headers = {
    "X-Profile-Id": "<x-profile-id>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Profile-Id': '<x-profile-id>',
    Authorization: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount_details: {currency: 'USD', order_amount: 6540},
    payment_method_data: {
      card: {
        card_cvc: '123',
        card_exp_month: '10',
        card_exp_year: '25',
        card_holder_name: 'joseph Doe',
        card_number: '4242424242424242'
      }
    },
    payment_method_subtype: 'credit',
    payment_method_type: 'card'
  })
};

fetch('https://sandbox.birrpay.io/v2/payments', 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://sandbox.birrpay.io/v2/payments",
  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([
    'amount_details' => [
        'currency' => 'USD',
        'order_amount' => 6540
    ],
    'payment_method_data' => [
        'card' => [
                'card_cvc' => '123',
                'card_exp_month' => '10',
                'card_exp_year' => '25',
                'card_holder_name' => 'joseph Doe',
                'card_number' => '4242424242424242'
        ]
    ],
    'payment_method_subtype' => 'credit',
    'payment_method_type' => 'card'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "X-Profile-Id: <x-profile-id>"
  ],
]);

$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://sandbox.birrpay.io/v2/payments"

	payload := strings.NewReader("{\n  \"amount_details\": {\n    \"currency\": \"USD\",\n    \"order_amount\": 6540\n  },\n  \"payment_method_data\": {\n    \"card\": {\n      \"card_cvc\": \"123\",\n      \"card_exp_month\": \"10\",\n      \"card_exp_year\": \"25\",\n      \"card_holder_name\": \"joseph Doe\",\n      \"card_number\": \"4242424242424242\"\n    }\n  },\n  \"payment_method_subtype\": \"credit\",\n  \"payment_method_type\": \"card\"\n}")

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

	req.Header.Add("X-Profile-Id", "<x-profile-id>")
	req.Header.Add("Authorization", "<api-key>")
	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://sandbox.birrpay.io/v2/payments")
  .header("X-Profile-Id", "<x-profile-id>")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount_details\": {\n    \"currency\": \"USD\",\n    \"order_amount\": 6540\n  },\n  \"payment_method_data\": {\n    \"card\": {\n      \"card_cvc\": \"123\",\n      \"card_exp_month\": \"10\",\n      \"card_exp_year\": \"25\",\n      \"card_holder_name\": \"joseph Doe\",\n      \"card_number\": \"4242424242424242\"\n    }\n  },\n  \"payment_method_subtype\": \"credit\",\n  \"payment_method_type\": \"card\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.birrpay.io/v2/payments")

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

request = Net::HTTP::Post.new(url)
request["X-Profile-Id"] = '<x-profile-id>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount_details\": {\n    \"currency\": \"USD\",\n    \"order_amount\": 6540\n  },\n  \"payment_method_data\": {\n    \"card\": {\n      \"card_cvc\": \"123\",\n      \"card_exp_month\": \"10\",\n      \"card_exp_year\": \"25\",\n      \"card_holder_name\": \"joseph Doe\",\n      \"card_number\": \"4242424242424242\"\n    }\n  },\n  \"payment_method_subtype\": \"credit\",\n  \"payment_method_type\": \"card\"\n}"

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

{
  "id": "12345_pay_01926c58bc6e77c09e809964e72af8c8",
  "status": "succeeded",
  "amount": {
    "currency": "AED",
    "external_tax_calculation": "skip",
    "surcharge_calculation": "skip",
    "net_amount": 123,
    "amount_capturable": 123,
    "order_amount": 6540,
    "shipping_cost": 123,
    "order_tax_amount": 123,
    "surcharge_amount": 123,
    "tax_on_surcharge": 123,
    "amount_to_capture": 123,
    "amount_captured": 123
  },
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "processor_merchant_id": "merchant_1689512302",
  "created": "2022-09-10T10:11:12Z",
  "modified_at": "2022-09-10T10:11:12Z",
  "initiator": "platform",
  "connector": "stripe",
  "payment_method_data": {
    "card": {
      "last4": "<string>",
      "card_type": "<string>",
      "card_network": "Visa",
      "card_issuer": "<string>",
      "card_issuing_country": "<string>",
      "card_isin": "<string>",
      "card_extended_bin": "<string>",
      "card_exp_month": "<string>",
      "card_exp_year": "<string>",
      "card_holder_name": "<string>",
      "payment_checks": null,
      "authentication_data": null
    },
    "billing": {
      "address": {
        "city": "New York",
        "country": "AF",
        "line1": "123, King Street",
        "line2": "Powelson Avenue",
        "line3": "Bridgewater",
        "zip": "08807",
        "state": "New York",
        "first_name": "John",
        "last_name": "Doe",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "<string>"
    }
  },
  "payment_method_type": "card",
  "payment_method_subtype": "ach",
  "connector_transaction_id": "993672945374576J",
  "connector_reference_id": "993672945374576J",
  "merchant_connector_id": "<string>",
  "browser_info": {
    "color_depth": 1,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "<string>",
    "screen_height": 1,
    "screen_width": 1,
    "time_zone": 123,
    "ip_address": "<string>",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "<string>",
    "os_type": "<string>",
    "os_version": "<string>",
    "device_model": "<string>",
    "accept_language": "<string>",
    "referer": "<string>"
  },
  "error": {
    "code": "card_declined",
    "message": "The card was declined.",
    "reason": "The card was declined.",
    "unified_code": "card_declined",
    "unified_message": "The card was declined.",
    "network_advice_code": "01",
    "network_decline_code": "05",
    "network_error_message": "Do not retry"
  },
  "shipping": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "<string>"
  },
  "billing": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "<string>"
  },
  "attempts": [
    {
      "id": "<string>",
      "status": "started",
      "amount": {
        "net_amount": 123,
        "amount_capturable": 123,
        "amount_to_capture": 123,
        "surcharge_amount": 123,
        "tax_on_surcharge": 123,
        "shipping_cost": 123,
        "order_tax_amount": 123,
        "amount_captured": 123
      },
      "authentication_type": "three_ds",
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "connector_payment_id": "<string>",
      "connector": "stripe",
      "error": {
        "code": "card_declined",
        "message": "The card was declined.",
        "reason": "The card was declined.",
        "unified_code": "card_declined",
        "unified_message": "The card was declined.",
        "network_advice_code": "01",
        "network_decline_code": "05",
        "network_error_message": "Do not retry"
      },
      "cancellation_reason": "<string>",
      "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
      "connector_metadata": {
        "apple_pay": {
          "session_token_data": {
            "payment_processing_certificate": "<string>",
            "payment_processing_certificate_key": "<string>",
            "payment_processing_details_at": "BirrPay",
            "certificate": "<string>",
            "certificate_keys": "<string>",
            "merchant_identifier": "<string>",
            "display_name": "<string>",
            "initiative": "web",
            "initiative_context": "<string>",
            "merchant_business_country": "AF"
          }
        },
        "airwallex": {
          "payload": "<string>"
        },
        "noon": {
          "order_category": "<string>"
        },
        "braintree": {
          "merchant_account_id": "<string>",
          "merchant_config_currency": "<string>"
        },
        "adyen": {
          "testing": {
            "holder_name": "<string>"
          }
        }
      },
      "payment_experience": "redirect_to_url",
      "payment_method_type": "card",
      "connector_reference_id": "993672945374576J",
      "payment_method_subtype": "ach",
      "payment_method_id": "12345_pm_01926c58bc6e77c09e809964e72af8c8",
      "client_source": "<string>",
      "client_version": "<string>",
      "feature_metadata": {
        "revenue_recovery": {
          "attempt_triggered_by": "internal",
          "charge_id": "ch_123abc456def789ghi012klmn"
        }
      },
      "payment_method_data": {
        "card": {
          "last4": "<string>",
          "card_type": "<string>",
          "card_network": "Visa",
          "card_issuer": "<string>",
          "card_issuing_country": "<string>",
          "card_isin": "<string>",
          "card_extended_bin": "<string>",
          "card_exp_month": "<string>",
          "card_exp_year": "<string>",
          "card_holder_name": "<string>",
          "payment_checks": null,
          "authentication_data": null
        },
        "billing": {
          "address": {
            "city": "New York",
            "country": "AF",
            "line1": "123, King Street",
            "line2": "Powelson Avenue",
            "line3": "Bridgewater",
            "zip": "08807",
            "state": "New York",
            "first_name": "John",
            "last_name": "Doe",
            "origin_zip": "08807"
          },
          "phone": {
            "number": "9123456789",
            "country_code": "+1"
          },
          "email": "<string>"
        }
      }
    }
  ],
  "connector_token_details": {
    "token": "pm_9UhMqBMEOooRIvJFFdeW",
    "connector_token_request_reference_id": "<string>"
  },
  "payment_method_id": "<string>",
  "next_action": {
    "redirect_to_url": "https://example.com/redirect",
    "type": "redirect_to_url"
  },
  "return_url": "<string>",
  "authentication_type": "no_three_ds",
  "authentication_type_applied": "no_three_ds",
  "is_iframe_redirection_enabled": true,
  "merchant_reference_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "raw_connector_response": "<string>",
  "feature_metadata": {
    "redirect_response": {
      "param": "<string>",
      "json_payload": {}
    },
    "search_tags": [
      "<string>"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "<string>",
      "regular_billing": {
        "label": "<string>",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_unit": "year",
        "recurring_payment_interval_count": 123
      },
      "management_url": "https://birrpay.io",
      "billing_agreement": "<string>"
    },
    "revenue_recovery": {
      "total_retry_count": "1",
      "billing_connector_id": "mca_1234567890",
      "active_attempt_payment_connector_id": "mca_1234567890",
      "billing_connector_payment_details": {
        "payment_processor_token": "<string>",
        "connector_customer_id": "<string>"
      },
      "payment_method_type": "card",
      "payment_method_subtype": "ach",
      "connector": "authipay",
      "billing_connector_payment_method_details": {
        "type": "card",
        "value": {
          "card_network": "Visa",
          "card_issuer": "JP MORGAN CHASE"
        }
      },
      "payment_connector_transmission": "ConnectorCallUnsuccessful",
      "invoice_next_billing_time": "2023-11-07T05:31:56Z",
      "invoice_billing_started_at_time": "2023-11-07T05:31:56Z",
      "first_payment_attempt_pg_error_code": "card_declined",
      "first_payment_attempt_network_decline_code": "05",
      "first_payment_attempt_network_advice_code": "02"
    }
  },
  "metadata": {}
}

{
  "error_type": "invalid_request",
  "message": "Missing required param: {param}",
  "code": "IR_04"
}

POST

payments

Payments - Create and Confirm Intent

curl --request POST \
  --url https://sandbox.birrpay.io/v2/payments \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'X-Profile-Id: <x-profile-id>' \
  --data '
{
  "amount_details": {
    "currency": "USD",
    "order_amount": 6540
  },
  "payment_method_data": {
    "card": {
      "card_cvc": "123",
      "card_exp_month": "10",
      "card_exp_year": "25",
      "card_holder_name": "joseph Doe",
      "card_number": "4242424242424242"
    }
  },
  "payment_method_subtype": "credit",
  "payment_method_type": "card"
}
'

import requests

url = "https://sandbox.birrpay.io/v2/payments"

payload = {
    "amount_details": {
        "currency": "USD",
        "order_amount": 6540
    },
    "payment_method_data": { "card": {
            "card_cvc": "123",
            "card_exp_month": "10",
            "card_exp_year": "25",
            "card_holder_name": "joseph Doe",
            "card_number": "4242424242424242"
        } },
    "payment_method_subtype": "credit",
    "payment_method_type": "card"
}
headers = {
    "X-Profile-Id": "<x-profile-id>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Profile-Id': '<x-profile-id>',
    Authorization: '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount_details: {currency: 'USD', order_amount: 6540},
    payment_method_data: {
      card: {
        card_cvc: '123',
        card_exp_month: '10',
        card_exp_year: '25',
        card_holder_name: 'joseph Doe',
        card_number: '4242424242424242'
      }
    },
    payment_method_subtype: 'credit',
    payment_method_type: 'card'
  })
};

fetch('https://sandbox.birrpay.io/v2/payments', 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://sandbox.birrpay.io/v2/payments",
  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([
    'amount_details' => [
        'currency' => 'USD',
        'order_amount' => 6540
    ],
    'payment_method_data' => [
        'card' => [
                'card_cvc' => '123',
                'card_exp_month' => '10',
                'card_exp_year' => '25',
                'card_holder_name' => 'joseph Doe',
                'card_number' => '4242424242424242'
        ]
    ],
    'payment_method_subtype' => 'credit',
    'payment_method_type' => 'card'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json",
    "X-Profile-Id: <x-profile-id>"
  ],
]);

$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://sandbox.birrpay.io/v2/payments"

	payload := strings.NewReader("{\n  \"amount_details\": {\n    \"currency\": \"USD\",\n    \"order_amount\": 6540\n  },\n  \"payment_method_data\": {\n    \"card\": {\n      \"card_cvc\": \"123\",\n      \"card_exp_month\": \"10\",\n      \"card_exp_year\": \"25\",\n      \"card_holder_name\": \"joseph Doe\",\n      \"card_number\": \"4242424242424242\"\n    }\n  },\n  \"payment_method_subtype\": \"credit\",\n  \"payment_method_type\": \"card\"\n}")

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

	req.Header.Add("X-Profile-Id", "<x-profile-id>")
	req.Header.Add("Authorization", "<api-key>")
	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://sandbox.birrpay.io/v2/payments")
  .header("X-Profile-Id", "<x-profile-id>")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount_details\": {\n    \"currency\": \"USD\",\n    \"order_amount\": 6540\n  },\n  \"payment_method_data\": {\n    \"card\": {\n      \"card_cvc\": \"123\",\n      \"card_exp_month\": \"10\",\n      \"card_exp_year\": \"25\",\n      \"card_holder_name\": \"joseph Doe\",\n      \"card_number\": \"4242424242424242\"\n    }\n  },\n  \"payment_method_subtype\": \"credit\",\n  \"payment_method_type\": \"card\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.birrpay.io/v2/payments")

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

request = Net::HTTP::Post.new(url)
request["X-Profile-Id"] = '<x-profile-id>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount_details\": {\n    \"currency\": \"USD\",\n    \"order_amount\": 6540\n  },\n  \"payment_method_data\": {\n    \"card\": {\n      \"card_cvc\": \"123\",\n      \"card_exp_month\": \"10\",\n      \"card_exp_year\": \"25\",\n      \"card_holder_name\": \"joseph Doe\",\n      \"card_number\": \"4242424242424242\"\n    }\n  },\n  \"payment_method_subtype\": \"credit\",\n  \"payment_method_type\": \"card\"\n}"

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

{
  "id": "12345_pay_01926c58bc6e77c09e809964e72af8c8",
  "status": "succeeded",
  "amount": {
    "currency": "AED",
    "external_tax_calculation": "skip",
    "surcharge_calculation": "skip",
    "net_amount": 123,
    "amount_capturable": 123,
    "order_amount": 6540,
    "shipping_cost": 123,
    "order_tax_amount": 123,
    "surcharge_amount": 123,
    "tax_on_surcharge": 123,
    "amount_to_capture": 123,
    "amount_captured": 123
  },
  "customer_id": "12345_cus_01926c58bc6e77c09e809964e72af8c8",
  "processor_merchant_id": "merchant_1689512302",
  "created": "2022-09-10T10:11:12Z",
  "modified_at": "2022-09-10T10:11:12Z",
  "initiator": "platform",
  "connector": "stripe",
  "payment_method_data": {
    "card": {
      "last4": "<string>",
      "card_type": "<string>",
      "card_network": "Visa",
      "card_issuer": "<string>",
      "card_issuing_country": "<string>",
      "card_isin": "<string>",
      "card_extended_bin": "<string>",
      "card_exp_month": "<string>",
      "card_exp_year": "<string>",
      "card_holder_name": "<string>",
      "payment_checks": null,
      "authentication_data": null
    },
    "billing": {
      "address": {
        "city": "New York",
        "country": "AF",
        "line1": "123, King Street",
        "line2": "Powelson Avenue",
        "line3": "Bridgewater",
        "zip": "08807",
        "state": "New York",
        "first_name": "John",
        "last_name": "Doe",
        "origin_zip": "08807"
      },
      "phone": {
        "number": "9123456789",
        "country_code": "+1"
      },
      "email": "<string>"
    }
  },
  "payment_method_type": "card",
  "payment_method_subtype": "ach",
  "connector_transaction_id": "993672945374576J",
  "connector_reference_id": "993672945374576J",
  "merchant_connector_id": "<string>",
  "browser_info": {
    "color_depth": 1,
    "java_enabled": true,
    "java_script_enabled": true,
    "language": "<string>",
    "screen_height": 1,
    "screen_width": 1,
    "time_zone": 123,
    "ip_address": "<string>",
    "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "user_agent": "<string>",
    "os_type": "<string>",
    "os_version": "<string>",
    "device_model": "<string>",
    "accept_language": "<string>",
    "referer": "<string>"
  },
  "error": {
    "code": "card_declined",
    "message": "The card was declined.",
    "reason": "The card was declined.",
    "unified_code": "card_declined",
    "unified_message": "The card was declined.",
    "network_advice_code": "01",
    "network_decline_code": "05",
    "network_error_message": "Do not retry"
  },
  "shipping": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "<string>"
  },
  "billing": {
    "address": {
      "city": "New York",
      "country": "AF",
      "line1": "123, King Street",
      "line2": "Powelson Avenue",
      "line3": "Bridgewater",
      "zip": "08807",
      "state": "New York",
      "first_name": "John",
      "last_name": "Doe",
      "origin_zip": "08807"
    },
    "phone": {
      "number": "9123456789",
      "country_code": "+1"
    },
    "email": "<string>"
  },
  "attempts": [
    {
      "id": "<string>",
      "status": "started",
      "amount": {
        "net_amount": 123,
        "amount_capturable": 123,
        "amount_to_capture": 123,
        "surcharge_amount": 123,
        "tax_on_surcharge": 123,
        "shipping_cost": 123,
        "order_tax_amount": 123,
        "amount_captured": 123
      },
      "authentication_type": "three_ds",
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "connector_payment_id": "<string>",
      "connector": "stripe",
      "error": {
        "code": "card_declined",
        "message": "The card was declined.",
        "reason": "The card was declined.",
        "unified_code": "card_declined",
        "unified_message": "The card was declined.",
        "network_advice_code": "01",
        "network_decline_code": "05",
        "network_error_message": "Do not retry"
      },
      "cancellation_reason": "<string>",
      "payment_token": "187282ab-40ef-47a9-9206-5099ba31e432",
      "connector_metadata": {
        "apple_pay": {
          "session_token_data": {
            "payment_processing_certificate": "<string>",
            "payment_processing_certificate_key": "<string>",
            "payment_processing_details_at": "BirrPay",
            "certificate": "<string>",
            "certificate_keys": "<string>",
            "merchant_identifier": "<string>",
            "display_name": "<string>",
            "initiative": "web",
            "initiative_context": "<string>",
            "merchant_business_country": "AF"
          }
        },
        "airwallex": {
          "payload": "<string>"
        },
        "noon": {
          "order_category": "<string>"
        },
        "braintree": {
          "merchant_account_id": "<string>",
          "merchant_config_currency": "<string>"
        },
        "adyen": {
          "testing": {
            "holder_name": "<string>"
          }
        }
      },
      "payment_experience": "redirect_to_url",
      "payment_method_type": "card",
      "connector_reference_id": "993672945374576J",
      "payment_method_subtype": "ach",
      "payment_method_id": "12345_pm_01926c58bc6e77c09e809964e72af8c8",
      "client_source": "<string>",
      "client_version": "<string>",
      "feature_metadata": {
        "revenue_recovery": {
          "attempt_triggered_by": "internal",
          "charge_id": "ch_123abc456def789ghi012klmn"
        }
      },
      "payment_method_data": {
        "card": {
          "last4": "<string>",
          "card_type": "<string>",
          "card_network": "Visa",
          "card_issuer": "<string>",
          "card_issuing_country": "<string>",
          "card_isin": "<string>",
          "card_extended_bin": "<string>",
          "card_exp_month": "<string>",
          "card_exp_year": "<string>",
          "card_holder_name": "<string>",
          "payment_checks": null,
          "authentication_data": null
        },
        "billing": {
          "address": {
            "city": "New York",
            "country": "AF",
            "line1": "123, King Street",
            "line2": "Powelson Avenue",
            "line3": "Bridgewater",
            "zip": "08807",
            "state": "New York",
            "first_name": "John",
            "last_name": "Doe",
            "origin_zip": "08807"
          },
          "phone": {
            "number": "9123456789",
            "country_code": "+1"
          },
          "email": "<string>"
        }
      }
    }
  ],
  "connector_token_details": {
    "token": "pm_9UhMqBMEOooRIvJFFdeW",
    "connector_token_request_reference_id": "<string>"
  },
  "payment_method_id": "<string>",
  "next_action": {
    "redirect_to_url": "https://example.com/redirect",
    "type": "redirect_to_url"
  },
  "return_url": "<string>",
  "authentication_type": "no_three_ds",
  "authentication_type_applied": "no_three_ds",
  "is_iframe_redirection_enabled": true,
  "merchant_reference_id": "pay_mbabizu24mvu3mela5njyhpit4",
  "raw_connector_response": "<string>",
  "feature_metadata": {
    "redirect_response": {
      "param": "<string>",
      "json_payload": {}
    },
    "search_tags": [
      "<string>"
    ],
    "apple_pay_recurring_details": {
      "payment_description": "<string>",
      "regular_billing": {
        "label": "<string>",
        "recurring_payment_start_date": "2023-09-10T23:59:59Z",
        "recurring_payment_end_date": "2023-09-10T23:59:59Z",
        "recurring_payment_interval_unit": "year",
        "recurring_payment_interval_count": 123
      },
      "management_url": "https://birrpay.io",
      "billing_agreement": "<string>"
    },
    "revenue_recovery": {
      "total_retry_count": "1",
      "billing_connector_id": "mca_1234567890",
      "active_attempt_payment_connector_id": "mca_1234567890",
      "billing_connector_payment_details": {
        "payment_processor_token": "<string>",
        "connector_customer_id": "<string>"
      },
      "payment_method_type": "card",
      "payment_method_subtype": "ach",
      "connector": "authipay",
      "billing_connector_payment_method_details": {
        "type": "card",
        "value": {
          "card_network": "Visa",
          "card_issuer": "JP MORGAN CHASE"
        }
      },
      "payment_connector_transmission": "ConnectorCallUnsuccessful",
      "invoice_next_billing_time": "2023-11-07T05:31:56Z",
      "invoice_billing_started_at_time": "2023-11-07T05:31:56Z",
      "first_payment_attempt_pg_error_code": "card_declined",
      "first_payment_attempt_network_decline_code": "05",
      "first_payment_attempt_network_advice_code": "02"
    }
  },
  "metadata": {}
}

{
  "error_type": "invalid_request",
  "message": "Missing required param: {param}",
  "code": "IR_04"
}

Authorizations

Authorization

string

header

required

Format: api-key=<api_key>

Use the API key created under your merchant account from the HyperSwitch dashboard. API key is used to authenticate API requests from your merchant server only. Don't expose this key on a website or embed it in a mobile application.

Headers

X-Profile-Id

string

required

Profile ID associated to the payment intent

Body

application/json

amount_details

object

required

Show child attributes

customer_id

string

required

The identifier for the customer

Required string length: 32 - 64

Example:

"12345_cus_01926c58bc6e77c09e809964e72af8c8"

payment_method_data

Card · object

required

The payment method information provided for making a payment

Show child attributes

payment_method_type

enum<string>

required

Indicates the type of payment method. Eg: 'card', 'wallet', etc.

Available options:

card,

card_redirect,

pay_later,

wallet,

bank_redirect,

bank_transfer,

crypto,

bank_debit,

reward,

real_time_payment,

upi,

voucher,

gift_card,

open_banking,

mobile_payment,

network_token

payment_method_subtype

enum<string>

required

Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.

Available options:

ach,

affirm,

afterpay_clearpay,

alfamart,

ali_pay,

ali_pay_hk,

alma,

amazon_pay,

paysera,

apple_pay,

atome,

bacs,

bancontact_card,

becs,

benefit,

bizum,

blik,

bluecode,

boleto,

bca_bank_transfer,

bni_va,

breadpay,

bri_va,

bhn_card_network,

card_redirect,

cimb_va,

classic,

credit,

crypto_currency,

cashapp,

dana,

danamon_va,

debit,

duit_now,

efecty,

eft,

eps,

flexiti,

fps,

evoucher,

giropay,

givex,

google_pay,

go_pay,

gcash,

ideal,

interac,

indomaret,

klarna,

kakao_pay,

local_bank_redirect,

mandiri_va,

knet,

mb_way,

mobile_pay,

momo,

momo_atm,

multibanco,

online_banking_thailand,

online_banking_czech_republic,

online_banking_finland,

online_banking_fpx,

online_banking_poland,

online_banking_slovakia,

oxxo,

pago_efectivo,

permata_bank_transfer,

open_banking_uk,

pay_bright,

payjustnow,

paypal,

paze,

pix,

pay_safe_card,

przelewy24,

prompt_pay,

pse,

qris,

red_compra,

red_pagos,

samsung_pay,

sepa,

sepa_bank_transfer,

sepa_guarenteed_debit,

skrill,

sofort,

swish,

touch_n_go,

trustly,

twint,

upi_collect,

upi_intent,

upi_qr,

vipps,

viet_qr,

venmo,

walley,

we_chat_pay,

seven_eleven,

lawson,

mini_stop,

family_mart,

seicomart,

pay_easy,

local_bank_transfer,

mifinity,

open_banking_pis,

direct_carrier_billing,

instant_bank_transfer,

instant_bank_transfer_finland,

instant_bank_transfer_poland,

revolut_pay,

indonesian_bank_transfer,

open_banking,

network_token

merchant_reference_id

string | null

Unique identifier for the payment. This ensures idempotency for multiple payments that have been done by a single merchant.

Required string length: 30

Example:

"pay_mbabizu24mvu3mela5njyhpit4"

routing_algorithm_id

string | null

The routing algorithm id to be used for the payment

capture_method

enum<string> | null

Specifies how the payment is captured.

automatic: Funds are captured immediately after successful authorization. This is the default behavior if the field is omitted.
manual: Funds are authorized but not captured. A separate request to the /payments/{payment_id}/capture endpoint is required to capture the funds.

Available options:

automatic,

manual,

manual_multiple,

scheduled,

sequential_automatic

authentication_type

enum<string> | null

default:no_three_ds

Specifies the type of cardholder authentication to be applied for a payment.

ThreeDs: Requests 3D Secure (3DS) authentication. If the card is enrolled, 3DS authentication will be activated, potentially shifting chargeback liability to the issuer.
NoThreeDs: Indicates that 3D Secure authentication should not be performed. The liability for chargebacks typically remains with the merchant. This is often the default if not specified.

Note: The actual authentication behavior can also be influenced by merchant configuration and specific connector defaults. Some connectors might still enforce 3DS or bypass it regardless of this parameter.

Available options:

three_ds,

no_three_ds

billing

object | null

Show child attributes

shipping

object | null

Show child attributes

customer_present

enum<string> | null

Set to present to indicate that the customer is in your checkout flow during this payment, and therefore is able to authenticate. This parameter should be absent when merchant's doing merchant initiated payments and customer is not present while doing the payment.

Available options:

present,

absent

description

string | null

A description for the payment

Example:

"It's my first payment request"

return_url

string | null

The URL to which you want the user to be redirected after the completion of the payment operation

Example:

"https://birrpay.io"

setup_future_usage

enum<string> | null

Specifies how the payment method can be used for future payments.

off_session: The payment method can be used for future payments when the customer is not present.
on_session: The payment method is intended for use only when the customer is present during checkout. If omitted, defaults to on_session.

Available options:

off_session,

on_session

apply_mit_exemption

enum<string> | null

Available options:

Apply,

Skip

statement_descriptor

string | null

For non-card charges, you can use this value as the complete description that appears on your customers’ statements. Must contain at least one letter, maximum 22 characters.

Maximum string length: 22

Example:

"BirrPay Router"

order_details

object[] | null

Use this object to capture the details about the different products for which the payment is being made. The sum of amount across different products here should be equal to the overall payment amount

Show child attributes

Example:

"[{\n \"product_name\": \"Apple iPhone 16\",\n \"quantity\": 1,\n \"amount\" : 69000\n \"product_img_link\" : \"https://dummy-img-link.com\"\n }]"

allowed_payment_method_types

enum<string>[] | null

Use this parameter to restrict the Payment Method Types to show for a given PaymentIntent

Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.

Available options:

ach,

affirm,

afterpay_clearpay,

alfamart,

ali_pay,

ali_pay_hk,

alma,

amazon_pay,

paysera,

apple_pay,

atome,

bacs,

bancontact_card,

becs,

benefit,

bizum,

blik,

bluecode,

boleto,

bca_bank_transfer,

bni_va,

breadpay,

bri_va,

bhn_card_network,

card_redirect,

cimb_va,

classic,

credit,

crypto_currency,

cashapp,

dana,

danamon_va,

debit,

duit_now,

efecty,

eft,

eps,

flexiti,

fps,

evoucher,

giropay,

givex,

google_pay,

go_pay,

gcash,

ideal,

interac,

indomaret,

klarna,

kakao_pay,

local_bank_redirect,

mandiri_va,

knet,

mb_way,

mobile_pay,

momo,

momo_atm,

multibanco,

online_banking_thailand,

online_banking_czech_republic,

online_banking_finland,

online_banking_fpx,

online_banking_poland,

online_banking_slovakia,

oxxo,

pago_efectivo,

permata_bank_transfer,

open_banking_uk,

pay_bright,

payjustnow,

paypal,

paze,

pix,

pay_safe_card,

przelewy24,

prompt_pay,

pse,

qris,

red_compra,

red_pagos,

samsung_pay,

sepa,

sepa_bank_transfer,

sepa_guarenteed_debit,

skrill,

sofort,

swish,

touch_n_go,

trustly,

twint,

upi_collect,

upi_intent,

upi_qr,

vipps,

viet_qr,

venmo,

walley,

we_chat_pay,

seven_eleven,

lawson,

mini_stop,

family_mart,

seicomart,

pay_easy,

local_bank_transfer,

mifinity,

open_banking_pis,

direct_carrier_billing,

instant_bank_transfer,

instant_bank_transfer_finland,

instant_bank_transfer_poland,

revolut_pay,

indonesian_bank_transfer,

open_banking,

network_token

metadata

object | null

Metadata is useful for storing additional, unstructured information on an object.

connector_metadata

object | null

Some connectors like Apple Pay, Airwallex and Noon might require some additional information, find specific details in the child attributes below.

Show child attributes

feature_metadata

object | null

additional data that might be required by hyperswitch

Show child attributes

payment_link_enabled

enum<string> | null

Whether payment link is requested to be enabled or not for this transaction

Available options:

Enable,

Skip

payment_link_config

object | null

Show child attributes

request_incremental_authorization

enum<string> | null

Available options:

true,

false,

default

session_expiry

integer<int32> | null

Will be used to expire client secret after certain amount of time to be supplied in seconds, if not sent it will be taken from profile config (900) for 15 mins

Required range: x >= 0

Example:

900

frm_metadata

object | null

Additional data related to some frm(Fraud Risk Management) connectors

request_external_three_ds_authentication

enum<string> | null

Whether 3ds authentication is requested or not

Available options:

Enable,

Skip

customer_acceptance

object | null

This "CustomerAcceptance" object is passed during Payments-Confirm request, it enlists the type, time, and mode of acceptance properties related to an acceptance done by the customer. The customer_acceptance sub object is usually passed by the SDK or client.

Show child attributes

browser_info

object | null

Browser information to be used for 3DS 2.0

Show child attributes

payment_method_id

string | null

The payment_method_id to be associated with the payment

force_3ds_challenge

boolean | null

Indicates if 3ds challenge is forced

is_iframe_redirection_enabled

boolean | null

Indicates if the redirection has to open in the iframe

merchant_connector_details

object | null

Merchant connector details

Show child attributes

return_raw_connector_response

boolean | null

Stringified connector raw response body. Only returned if return_raw_connector_response is true

enable_partial_authorization

boolean | null

default:false

Allow partial authorization for this payment

webhook_url

string | null

The webhook endpoint URL to receive payment status notifications

Example:

"https://merchant.example.com/webhooks/payment"

Response

Payment created

Response for Payment Intent Confirm Few fields should be expandable, we need not return these in the normal response But when explicitly requested for expanded objects, these can be returned For example shipping, billing, customer, payment_method

string

required

Unique identifier for the payment. This ensures idempotency for multiple payments that have been done by a single merchant.

Required string length: 32 - 64

Example:

"12345_pay_01926c58bc6e77c09e809964e72af8c8"

status

enum<string>

required

Represents the overall status of a payment intent. The status transitions through various states depending on the payment method, confirmation, capture method, and any subsequent actions (like customer authentication or manual capture).

Available options:

succeeded,

failed,

cancelled,

cancelled_post_capture,

processing,

requires_customer_action,

requires_merchant_action,

requires_payment_method,

requires_confirmation,

requires_capture,

partially_captured,

partially_captured_and_capturable,

partially_authorized_and_requires_capture,

partially_captured_and_processing,

conflicted,

expired

amount

object

required

Show child attributes

customer_id

string

required

The identifier for the customer

Required string length: 32 - 64

Example:

"12345_cus_01926c58bc6e77c09e809964e72af8c8"

processor_merchant_id

string

required

The identifier for the processor merchant account. In platform-connected setups, this is the connected merchant ID. For standard merchants, this is same as merchant_id.

Maximum string length: 255

Example:

"merchant_1689512302"

created

string<date-time>

required

Time when the payment was created

Example:

"2022-09-10T10:11:12Z"

modified_at

string<date-time>

required

Time when the payment was last modified

Example:

"2022-09-10T10:11:12Z"

initiator

enum<string> | null

Represents the initiator context in platform-connected setups Used in payment/refund/dispute responses to indicate who initiated the operation None indicates a standard merchant flow / JWT flow / Admin flow or insufficient information

Available options:

platform,

connected

connector

string | null

The connector used for the payment

Example:

"stripe"

payment_method_data

object

Show child attributes

payment_method_type

enum<string> | null

Indicates the type of payment method. Eg: 'card', 'wallet', etc.

Available options:

card,

card_redirect,

pay_later,

wallet,

bank_redirect,

bank_transfer,

crypto,

bank_debit,

reward,

real_time_payment,

upi,

voucher,

gift_card,

open_banking,

mobile_payment,

network_token

payment_method_subtype

enum<string> | null

Indicates the sub type of payment method. Eg: 'google_pay' & 'apple_pay' for wallets.

Available options:

ach,

affirm,

afterpay_clearpay,

alfamart,

ali_pay,

ali_pay_hk,

alma,

amazon_pay,

paysera,

apple_pay,

atome,

bacs,

bancontact_card,

becs,

benefit,

bizum,

blik,

bluecode,

boleto,

bca_bank_transfer,

bni_va,

breadpay,

bri_va,

bhn_card_network,

card_redirect,

cimb_va,

classic,

credit,

crypto_currency,

cashapp,

dana,

danamon_va,

debit,

duit_now,

efecty,

eft,

eps,

flexiti,

fps,

evoucher,

giropay,

givex,

google_pay,

go_pay,

gcash,

ideal,

interac,

indomaret,

klarna,

kakao_pay,

local_bank_redirect,

mandiri_va,

knet,

mb_way,

mobile_pay,

momo,

momo_atm,

multibanco,

online_banking_thailand,

online_banking_czech_republic,

online_banking_finland,

online_banking_fpx,

online_banking_poland,

online_banking_slovakia,

oxxo,

pago_efectivo,

permata_bank_transfer,

open_banking_uk,

pay_bright,

payjustnow,

paypal,

paze,

pix,

pay_safe_card,

przelewy24,

prompt_pay,

pse,

qris,

red_compra,

red_pagos,

samsung_pay,

sepa,

sepa_bank_transfer,

sepa_guarenteed_debit,

skrill,

sofort,

swish,

touch_n_go,

trustly,

twint,

upi_collect,

upi_intent,

upi_qr,

vipps,

viet_qr,

venmo,

walley,

we_chat_pay,

seven_eleven,

lawson,

mini_stop,

family_mart,

seicomart,

pay_easy,

local_bank_transfer,

mifinity,

open_banking_pis,

direct_carrier_billing,

instant_bank_transfer,

instant_bank_transfer_finland,

instant_bank_transfer_poland,

revolut_pay,

indonesian_bank_transfer,

open_banking,

network_token

connector_transaction_id

string | null

A unique identifier for a payment provided by the connector

Example:

"993672945374576J"

connector_reference_id

string | null

reference(Identifier) to the payment at connector side

Example:

"993672945374576J"

merchant_connector_id

string | null

Identifier of the connector ( merchant connector account ) which was chosen to make the payment

browser_info

object | null

Browser information to be used for 3DS 2.0

Show child attributes

error

object | null

Error details for the payment

Show child attributes

shipping

object | null

Show child attributes

billing

object | null

Show child attributes

attempts

object[] | null

List of payment attempts associated with payment intent

Show child attributes

connector_token_details

object | null

Token information that can be used to initiate transactions by the merchant.

Show child attributes

payment_method_id

string | null

The payment_method_id associated with the payment

next_action

object

Contains the url for redirection flow

Show child attributes

return_url

string | null

The url to which user must be redirected to after completion of the purchase

authentication_type

enum<string> | null

default:no_three_ds

Specifies the type of cardholder authentication to be applied for a payment.

ThreeDs: Requests 3D Secure (3DS) authentication. If the card is enrolled, 3DS authentication will be activated, potentially shifting chargeback liability to the issuer.
NoThreeDs: Indicates that 3D Secure authentication should not be performed. The liability for chargebacks typically remains with the merchant. This is often the default if not specified.

Available options:

three_ds,

no_three_ds

authentication_type_applied

enum<string> | null

default:no_three_ds

Specifies the type of cardholder authentication to be applied for a payment.

ThreeDs: Requests 3D Secure (3DS) authentication. If the card is enrolled, 3DS authentication will be activated, potentially shifting chargeback liability to the issuer.
NoThreeDs: Indicates that 3D Secure authentication should not be performed. The liability for chargebacks typically remains with the merchant. This is often the default if not specified.

Available options:

three_ds,

no_three_ds

is_iframe_redirection_enabled

boolean | null

Indicates if the redirection has to open in the iframe

merchant_reference_id

string | null

Unique identifier for the payment. This ensures idempotency for multiple payments that have been done by a single merchant.

Required string length: 30

Example:

"pay_mbabizu24mvu3mela5njyhpit4"

raw_connector_response

string | null

Stringified connector raw response body. Only returned if return_raw_connector_response is true

feature_metadata

object | null

additional data that might be required by hyperswitch

Show child attributes

metadata

object | null

You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. Metadata is useful for storing additional, structured information on an object.

Get Started [BETA]

Essentials [BETA]

Payments Core APIs [BETA]

Account management APIs [BETA]

Other APIs [BETA]

Payments - Create and Confirm Intent

Authorizations

Headers

Body

Response