Overview
Your First Payment
Payment Operations
Advanced Features
Webhooks & Events
Your First Payment
Payments - Create
Use this API to initiate a payment.
When you create a payment, it is stored with GreenBanana. At this stage, the payment intent is generated but requires confirmation from either the user or merchant to proceed.
Once confirmed (by including confirm=true and payment_method), the request is sent to the selected BNPL provider to verify if the customer is eligible for credit to proceed with the Buy Now, Pay Later (BNPL) provider.
The following request body example demonstrates how to create a payment with GreenBanana, which can be processed through any BNPL provider.
Note: The metadata field is used to carry additional information required by the BNPL provider. We have compiled all necessary metadata fields to ensure compatibility with any BNPL provider.
POST
/
payments
Copy
curl --request POST \
--url https://api.staging.bnplx.io/payments \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '{
"amount": 10000,
"amount_to_capture": 10250,
"authentication_type": "no_three_ds",
"billing": {
"address": {
"city": "San Fransico",
"country": "DE",
"first_name": "joseph",
"last_name": "Doe",
"line1": "Schönhauser Allee",
"line2": "Harrison Street",
"line3": "Harrison Street",
"state": "California",
"zip": "24000"
},
"email": "guest@example.com",
"phone": {
"country_code": "+49",
"number": "8056594427"
}
},
"browser_info": {
"ip_address": "192.168.127.1"
},
"capture_method": "manual_multiple",
"capture_on": "2022-09-10T10:11:12Z",
"confirm": false,
"currency": "EUR",
"customer": {
"birth_date": "2001-10-19",
"email": "guest@example.com",
"gender": "male",
"id": "cust_01",
"locale": "en_US",
"name": "john doe",
"phone": "177555923",
"phone_country_code": "+91",
"ssn": "030883-925M"
},
"description": "Its my first payment request",
"merchant_order_reference_id": "asdbcdef",
"metadata": {
"birth_date": "2001-10-19",
"buyer_type": "private_person",
"company_name": "Your company GmbH",
"company_vat_id": null,
"customer_locale": "en-GB",
"device_token": "abcddef",
"gender": "M",
"invoice_url": "https://www.google.com",
"legal_form": "gmbh",
"legal_form_category": "einzelunternehmen",
"net_term": 30,
"order_dttm": "2021-10-01 10:10:10.222",
"product_ref": null,
"settlement": "settlement1234",
"user_language_code": 208
},
"order_details": [
{
"amount": 5000,
"product_id": "i122",
"product_name": "Apple iphone 15",
"quantity": 1,
"tax_amount": 125,
"tax_percentage": 10
},
{
"amount": 5000,
"product_id": "i124",
"product_name": "Apple airpods",
"quantity": 1,
"tax_amount": 125,
"tax_percentage": 10
},
{
"amount": 500,
"category": "shipping_costs",
"product_id": "i123",
"product_name": "Shipping",
"quantity": 1,
"tax_amount": 50,
"tax_percentage": 5
},
{
"amount": 500,
"category": "voucher",
"product_id": "i123",
"product_name": "Voucher",
"quantity": 1,
"tax_amount": 50,
"tax_percentage": 5
}
],
"order_tax_amount": 250,
"payment_method": "pay_later",
"payment_method_data": {
"pay_later": {
"invoice": {}
}
},
"payment_method_type": "invoice",
"return_url": "https://google.com",
"shipping": {
"address": {
"city": "San Fransico",
"country": "DE",
"first_name": "joseph",
"last_name": "Doe",
"line1": "Schönhauser Allee",
"line2": "Harrison Street",
"line3": "Harrison Street",
"state": "California",
"zip": "24000"
},
"phone": {
"country_code": "+49",
"number": "8056594427"
}
},
"statement_descriptor_name": "joseph",
"statement_descriptor_suffix": "JS"
}'Copy
{
"allowed_payment_method_types": null,
"amount": 10000,
"amount_cancelled": null,
"amount_capturable": 0,
"amount_received": null,
"attempt_count": 1,
"authentication_type": "no_three_ds",
"authorization_count": null,
"billing": {
"address": {
"city": "San Fransico",
"country": "DE",
"first_name": "joseph",
"last_name": "Doe",
"line1": "Schönhauser Allee",
"line2": "Harrison Street",
"line3": "Harrison Street",
"state": "California",
"zip": "24000"
},
"email": "guest@example.com",
"phone": {
"country_code": "+49",
"number": "8056594427"
}
},
"birth_date": "2001-10-19",
"browser_info": {
"ip_address": "192.168.127.1"
},
"business_country": null,
"business_label": "default",
"business_sub_label": null,
"cancellation_reason": null,
"capture_method": "manual_multiple",
"capture_on": null,
"client_secret": "pay_m7cthQvCluxCi5rfpu69_secret_SxeEfmQp6j76ijKY6cT7",
"connector": null,
"connector_label": null,
"connector_mandate_id": null,
"connector_metadata": null,
"connector_transaction_id": null,
"created": "2025-05-22T12:14:29.694Z",
"currency": "EUR",
"customer": {
"email": "guest@example.com",
"id": "cust_01",
"name": "john doe",
"phone": "177555923",
"phone_country_code": "+91"
},
"customer_id": "cust_01",
"description": "Its my first payment request",
"disputes": null,
"email": "guest@example.com",
"ephemeral_key": {
"created_at": 1747916069,
"customer_id": "cust_01",
"expires": 1747919669,
"secret": "epk_ef52ca76e06a4ddca2b253cad451b671"
},
"error_code": null,
"error_message": null,
"expires_on": "2025-05-22T12:29:29.694Z",
"external_3ds_authentication_attempted": false,
"external_authentication_details": null,
"feature_metadata": null,
"fingerprint": null,
"frm_message": null,
"frm_metadata": null,
"gender": "male",
"incremental_authorization_allowed": null,
"incremental_authorizations": null,
"locale": "en_US",
"mandate_data": null,
"mandate_id": null,
"manual_retry_allowed": null,
"merchant_connector_id": null,
"merchant_decision": null,
"merchant_id": "merchant_1735914184",
"merchant_order_reference_id": "asdbcdef",
"metadata": {
"birth_date": "2001-10-19",
"buyer_type": "private_person",
"company_name": "Your company GmbH",
"company_vat_id": null,
"customer_locale": "en-GB",
"device_token": "abcddef",
"gender": "M",
"invoice_url": "https://www.google.com",
"legal_form": "gmbh",
"legal_form_category": "einzelunternehmen",
"net_term": 30,
"order_dttm": "2021-10-01 10:10:10.222",
"product_ref": null,
"settlement": "settlement1234",
"user_language_code": 208
},
"name": "john doe",
"net_amount": 10000,
"next_action": null,
"off_session": null,
"order_details": [
{
"amount": 5000,
"brand": null,
"category": null,
"product_id": "i122",
"product_img_link": null,
"product_link": null,
"product_name": "Apple iphone 15",
"product_tax_code": null,
"product_type": null,
"quantity": 1,
"requires_shipping": null,
"sub_category": null,
"tax_amount": 100,
"tax_percentage": 10,
"total_tax_amount": null
},
{
"amount": 2000,
"brand": null,
"category": null,
"product_id": "i124",
"product_img_link": null,
"product_link": null,
"product_name": "Apple airpods",
"product_tax_code": null,
"product_type": null,
"quantity": 2,
"requires_shipping": null,
"sub_category": null,
"tax_amount": 50,
"tax_percentage": 10,
"total_tax_amount": null
},
{
"amount": 1000,
"brand": null,
"category": null,
"product_id": "i124",
"product_img_link": null,
"product_link": null,
"product_name": "Apple airpods",
"product_tax_code": null,
"product_type": null,
"quantity": 1,
"requires_shipping": null,
"sub_category": null,
"tax_amount": 50,
"tax_percentage": 10,
"total_tax_amount": null
},
{
"amount": 500,
"brand": null,
"category": "shipping_costs",
"product_id": "i123",
"product_img_link": null,
"product_link": null,
"product_name": "Shipping",
"product_tax_code": null,
"product_type": null,
"quantity": 1,
"requires_shipping": null,
"sub_category": null,
"tax_amount": 50,
"tax_percentage": 5,
"total_tax_amount": null
},
{
"amount": 500,
"brand": null,
"category": "voucher",
"product_id": "i123",
"product_img_link": null,
"product_link": null,
"product_name": "Voucher",
"product_tax_code": null,
"product_type": null,
"quantity": 1,
"requires_shipping": null,
"sub_category": null,
"tax_amount": 50,
"tax_percentage": 5,
"total_tax_amount": null
}
],
"order_tax_amount": 250,
"payment_experience": null,
"payment_id": "pay_m7cthQvCluxCi5rfpu69",
"payment_link": null,
"payment_method": "pay_later",
"payment_method_data": {
"billing": null,
"pay_later": {
"klarna_sdk": null
}
},
"payment_method_id": null,
"payment_method_status": null,
"payment_method_type": "invoice",
"payment_token": null,
"phone": "177555923",
"profile_id": "pro_WzNsrevpecY0FYP7Rd9v",
"reference_id": null,
"refunds": null,
"return_url": "https://google.com/",
"setup_future_usage": null,
"shipping": {
"address": {
"city": "San Fransico",
"country": "DE",
"first_name": "joseph",
"last_name": "Doe",
"line1": "Schönhauser Allee",
"line2": "Harrison Street",
"line3": "Harrison Street",
"state": "California",
"zip": "24000"
},
"email": null,
"phone": {
"country_code": "+49",
"number": "8056594427"
}
},
"shipping_cost": null,
"split_payments": null,
"ssn": "030883-925M",
"statement_descriptor_name": "joseph",
"statement_descriptor_suffix": "JS",
"status": "requires_confirmation",
"surcharge_details": null,
"unified_code": null,
"unified_message": null,
"updated": "2025-05-22T12:14:29.740Z"
}Authorizations
Use the API key created under your merchant account from the GreenBanana 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.
Body
application/json
Response
200
application/json
Payment created
The response is of type object.
Copy
curl --request POST \
--url https://api.staging.bnplx.io/payments \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '{
"amount": 10000,
"amount_to_capture": 10250,
"authentication_type": "no_three_ds",
"billing": {
"address": {
"city": "San Fransico",
"country": "DE",
"first_name": "joseph",
"last_name": "Doe",
"line1": "Schönhauser Allee",
"line2": "Harrison Street",
"line3": "Harrison Street",
"state": "California",
"zip": "24000"
},
"email": "guest@example.com",
"phone": {
"country_code": "+49",
"number": "8056594427"
}
},
"browser_info": {
"ip_address": "192.168.127.1"
},
"capture_method": "manual_multiple",
"capture_on": "2022-09-10T10:11:12Z",
"confirm": false,
"currency": "EUR",
"customer": {
"birth_date": "2001-10-19",
"email": "guest@example.com",
"gender": "male",
"id": "cust_01",
"locale": "en_US",
"name": "john doe",
"phone": "177555923",
"phone_country_code": "+91",
"ssn": "030883-925M"
},
"description": "Its my first payment request",
"merchant_order_reference_id": "asdbcdef",
"metadata": {
"birth_date": "2001-10-19",
"buyer_type": "private_person",
"company_name": "Your company GmbH",
"company_vat_id": null,
"customer_locale": "en-GB",
"device_token": "abcddef",
"gender": "M",
"invoice_url": "https://www.google.com",
"legal_form": "gmbh",
"legal_form_category": "einzelunternehmen",
"net_term": 30,
"order_dttm": "2021-10-01 10:10:10.222",
"product_ref": null,
"settlement": "settlement1234",
"user_language_code": 208
},
"order_details": [
{
"amount": 5000,
"product_id": "i122",
"product_name": "Apple iphone 15",
"quantity": 1,
"tax_amount": 125,
"tax_percentage": 10
},
{
"amount": 5000,
"product_id": "i124",
"product_name": "Apple airpods",
"quantity": 1,
"tax_amount": 125,
"tax_percentage": 10
},
{
"amount": 500,
"category": "shipping_costs",
"product_id": "i123",
"product_name": "Shipping",
"quantity": 1,
"tax_amount": 50,
"tax_percentage": 5
},
{
"amount": 500,
"category": "voucher",
"product_id": "i123",
"product_name": "Voucher",
"quantity": 1,
"tax_amount": 50,
"tax_percentage": 5
}
],
"order_tax_amount": 250,
"payment_method": "pay_later",
"payment_method_data": {
"pay_later": {
"invoice": {}
}
},
"payment_method_type": "invoice",
"return_url": "https://google.com",
"shipping": {
"address": {
"city": "San Fransico",
"country": "DE",
"first_name": "joseph",
"last_name": "Doe",
"line1": "Schönhauser Allee",
"line2": "Harrison Street",
"line3": "Harrison Street",
"state": "California",
"zip": "24000"
},
"phone": {
"country_code": "+49",
"number": "8056594427"
}
},
"statement_descriptor_name": "joseph",
"statement_descriptor_suffix": "JS"
}'Copy
{
"allowed_payment_method_types": null,
"amount": 10000,
"amount_cancelled": null,
"amount_capturable": 0,
"amount_received": null,
"attempt_count": 1,
"authentication_type": "no_three_ds",
"authorization_count": null,
"billing": {
"address": {
"city": "San Fransico",
"country": "DE",
"first_name": "joseph",
"last_name": "Doe",
"line1": "Schönhauser Allee",
"line2": "Harrison Street",
"line3": "Harrison Street",
"state": "California",
"zip": "24000"
},
"email": "guest@example.com",
"phone": {
"country_code": "+49",
"number": "8056594427"
}
},
"birth_date": "2001-10-19",
"browser_info": {
"ip_address": "192.168.127.1"
},
"business_country": null,
"business_label": "default",
"business_sub_label": null,
"cancellation_reason": null,
"capture_method": "manual_multiple",
"capture_on": null,
"client_secret": "pay_m7cthQvCluxCi5rfpu69_secret_SxeEfmQp6j76ijKY6cT7",
"connector": null,
"connector_label": null,
"connector_mandate_id": null,
"connector_metadata": null,
"connector_transaction_id": null,
"created": "2025-05-22T12:14:29.694Z",
"currency": "EUR",
"customer": {
"email": "guest@example.com",
"id": "cust_01",
"name": "john doe",
"phone": "177555923",
"phone_country_code": "+91"
},
"customer_id": "cust_01",
"description": "Its my first payment request",
"disputes": null,
"email": "guest@example.com",
"ephemeral_key": {
"created_at": 1747916069,
"customer_id": "cust_01",
"expires": 1747919669,
"secret": "epk_ef52ca76e06a4ddca2b253cad451b671"
},
"error_code": null,
"error_message": null,
"expires_on": "2025-05-22T12:29:29.694Z",
"external_3ds_authentication_attempted": false,
"external_authentication_details": null,
"feature_metadata": null,
"fingerprint": null,
"frm_message": null,
"frm_metadata": null,
"gender": "male",
"incremental_authorization_allowed": null,
"incremental_authorizations": null,
"locale": "en_US",
"mandate_data": null,
"mandate_id": null,
"manual_retry_allowed": null,
"merchant_connector_id": null,
"merchant_decision": null,
"merchant_id": "merchant_1735914184",
"merchant_order_reference_id": "asdbcdef",
"metadata": {
"birth_date": "2001-10-19",
"buyer_type": "private_person",
"company_name": "Your company GmbH",
"company_vat_id": null,
"customer_locale": "en-GB",
"device_token": "abcddef",
"gender": "M",
"invoice_url": "https://www.google.com",
"legal_form": "gmbh",
"legal_form_category": "einzelunternehmen",
"net_term": 30,
"order_dttm": "2021-10-01 10:10:10.222",
"product_ref": null,
"settlement": "settlement1234",
"user_language_code": 208
},
"name": "john doe",
"net_amount": 10000,
"next_action": null,
"off_session": null,
"order_details": [
{
"amount": 5000,
"brand": null,
"category": null,
"product_id": "i122",
"product_img_link": null,
"product_link": null,
"product_name": "Apple iphone 15",
"product_tax_code": null,
"product_type": null,
"quantity": 1,
"requires_shipping": null,
"sub_category": null,
"tax_amount": 100,
"tax_percentage": 10,
"total_tax_amount": null
},
{
"amount": 2000,
"brand": null,
"category": null,
"product_id": "i124",
"product_img_link": null,
"product_link": null,
"product_name": "Apple airpods",
"product_tax_code": null,
"product_type": null,
"quantity": 2,
"requires_shipping": null,
"sub_category": null,
"tax_amount": 50,
"tax_percentage": 10,
"total_tax_amount": null
},
{
"amount": 1000,
"brand": null,
"category": null,
"product_id": "i124",
"product_img_link": null,
"product_link": null,
"product_name": "Apple airpods",
"product_tax_code": null,
"product_type": null,
"quantity": 1,
"requires_shipping": null,
"sub_category": null,
"tax_amount": 50,
"tax_percentage": 10,
"total_tax_amount": null
},
{
"amount": 500,
"brand": null,
"category": "shipping_costs",
"product_id": "i123",
"product_img_link": null,
"product_link": null,
"product_name": "Shipping",
"product_tax_code": null,
"product_type": null,
"quantity": 1,
"requires_shipping": null,
"sub_category": null,
"tax_amount": 50,
"tax_percentage": 5,
"total_tax_amount": null
},
{
"amount": 500,
"brand": null,
"category": "voucher",
"product_id": "i123",
"product_img_link": null,
"product_link": null,
"product_name": "Voucher",
"product_tax_code": null,
"product_type": null,
"quantity": 1,
"requires_shipping": null,
"sub_category": null,
"tax_amount": 50,
"tax_percentage": 5,
"total_tax_amount": null
}
],
"order_tax_amount": 250,
"payment_experience": null,
"payment_id": "pay_m7cthQvCluxCi5rfpu69",
"payment_link": null,
"payment_method": "pay_later",
"payment_method_data": {
"billing": null,
"pay_later": {
"klarna_sdk": null
}
},
"payment_method_id": null,
"payment_method_status": null,
"payment_method_type": "invoice",
"payment_token": null,
"phone": "177555923",
"profile_id": "pro_WzNsrevpecY0FYP7Rd9v",
"reference_id": null,
"refunds": null,
"return_url": "https://google.com/",
"setup_future_usage": null,
"shipping": {
"address": {
"city": "San Fransico",
"country": "DE",
"first_name": "joseph",
"last_name": "Doe",
"line1": "Schönhauser Allee",
"line2": "Harrison Street",
"line3": "Harrison Street",
"state": "California",
"zip": "24000"
},
"email": null,
"phone": {
"country_code": "+49",
"number": "8056594427"
}
},
"shipping_cost": null,
"split_payments": null,
"ssn": "030883-925M",
"statement_descriptor_name": "joseph",
"statement_descriptor_suffix": "JS",
"status": "requires_confirmation",
"surcharge_details": null,
"unified_code": null,
"unified_message": null,
"updated": "2025-05-22T12:14:29.740Z"
}Assistant
Responses are generated using AI and may contain mistakes.