The CommerceCore Payment Microservice provides a robust and flexible API for managing various aspects of payment processing for the CommerceCore API. This API is designed to seamlessly integrate with Stripe's payment infrastructure while offering additional features and abstractions tailored for CommerceCore's ecosystem. The API is structured around three main components: Connected Accounts, Transactions, and Refunds.
\nThe Connected Accounts feature allows businesses to create and manage their own payment processing accounts within the CommerceCore ecosystem. This is particularly useful for marketplaces or platforms that need to handle payments on behalf of multiple sellers or service providers.
\nKey functionalities include:
\nCreating Connected Accounts: Businesses can easily set up new accounts by providing an email address. This process generates a Stripe Connected Account, providing a unique account ID and public key for future transactions.
\nAccount Onboarding: The API facilitates the onboarding process for new accounts, ensuring that all necessary information is collected to comply with financial regulations and Stripe's requirements.
\nDashboard Access: Account holders can securely access their Stripe dashboard through a generated login link, allowing them to manage their account settings, view transaction history, and access financial reports.
\nThese features enable platforms to quickly set up and manage multiple seller accounts, streamlining the process of integrating diverse businesses into a single payment ecosystem.
\nThe Transactions component forms the core of the payment processing functionality, handling the creation and confirmation of payment intents.
\nKey features include:
\nInitiating Transactions: The API allows for the creation of new transactions by specifying details such as the order ID, connected account ID, and transaction amount. This process generates a client secret and transaction ID, which are crucial for completing the payment on the client side.
\nConfirming Transactions: Once a payment method is selected by the customer, the transaction can be confirmed using the API. This step finalizes the payment, moving it from an initiated state to a completed state.
\nThe transaction process is designed to be flexible and secure, allowing for various payment flows including delayed capture for pre-authorization scenarios.
\nThe Refunds component handles the process of returning funds to customers, which is a critical part of any e-commerce platform.
\nKey functionality:
\nThe refund system is designed to be straightforward yet flexible, accommodating various refund scenarios that may arise in complex e-commerce operations.
\nAcross all these components, the API implements several important features:
\nAuthentication and Authorization: The API uses a multi-layered authentication system, including bearer tokens for overall API access, developer tokens for identifying the integrating application, and user IDs for attributing actions to specific users within the system.
\nError Handling: Comprehensive error reporting is implemented across all endpoints, providing clear and actionable information when issues arise.
\nStripe Integration: While abstracting many of the complexities, the API closely integrates with Stripe's services, leveraging its robust payment processing capabilities and security features.
\nExtensibility: The API is designed with future growth in mind, allowing for easy addition of new features and endpoints as the needs of the platform evolve.
\nThis API provides a comprehensive solution for platforms and marketplaces looking to implement complex payment flows. By abstracting much of the complexity involved in multi-party payments, refunds, and account management, it allows businesses to focus on their core operations while still maintaining flexibility and control over their payment processes.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"36378381","collectionId":"ecb64938-862b-42ff-9d04-b51c7a97d6c5","publishedId":"2sAXqtb23V","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2024-09-26T09:16:12.000Z"},"item":[{"name":"Version 1","item":[{"name":"Connected Accounts","item":[{"name":"Create Connected Account","id":"4e8ab493-b138-4ab0-ae49-23e1df36958e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"X-Developer-Token","value":"214c0063-6017-46be-a9a7-a633ac55e65d","description":"Token of authorized developer
\n","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"email\": \"ezewisdomjohn@gmail.com\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://commercecore-payment-api-bbdd0516ee91.herokuapp.com/api/v1/connected-accounts","description":"This endpoint allows you to create a new connected Stripe account within the CommerceCore Payment Microservice ecosystem.
\nX-Developer-Token (required)
\nType: String
\nDescription: A used for authentication and authorization.
\nFormat: Bearer
X-Developer-Token:
\nThe request body should be in JSON format and contain the following field:
\nemail (required)
\nType: String
\nDescription: The email address associated with the connected account to be created.
\nFormat: A valid email address
\n{ \"email\": \"ezeisraeljohn@example.com\"}
\nStatus Code: 201 Created
\nThe response body will be a JSON object with the following structure:
\n{\n \"data\": {\n \"account_id\": \"acct_1Q05C3FNeyusjZzz\",\n \"public_key\": \"pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n \"message\": \"Connected account created successfully onboarding link expires in 18 hours use the 'onboarding_url' to complete the onboarding\"\n },\n \"meta\": {\n \"status_code\": 201\n },\n \"links\": {\n \"self\": https://commercecore-payment-api-bbdd0516ee91.herokuapp.com/api/v1/connected-accounts,\n \"onboarding_url\": \"https://connect.stripe.com/setup/e/acct_1xxxxxxxxxxxxxxx\"\n }\n}\n\ndata
\naccount_id: A unique identifier for the created Stripe connected account. This ID should be stored securely as it will be used for future operations related to this account.
\npublic_key: The Stripe public key associated with this connected account. This key can be used for client-side operations specific to this account.
\nmessage: A human-readable message indicating the successful creation of the account and providing instructions for the next steps.
\nmeta
\nlinks
\nself: The URL of the endpoint that was called to create this account.
\nonboarding_url: A Stripe-hosted URL where the account holder can complete the onboarding process. This URL is time-sensitive and typically expires after 18 hours.
\nUnauthorized (401)
\nOccurs when the X-Developer-Token is missing, invalid, or expired.
\n{ \"detail\": \"Invalid or expired token\"}
\nBad Request (400)
\nOccurs when the request body is malformed or missing required fields.
\n{ \"detail\": \"Invalid request body. 'email' field is required.\"}
\nConflict (409)
\nMight occur if an account with the provided email already exists.
\n{ \"detail\": \"An account with this email already exists.\"}
\nInternal Server Error (500)
\nOccurs when there's an unexpected error on the server side.
\n{ \"detail\": \"An unexpected error occurred while processing your request.\"}
\nEmail Validation: The service performs basic validation on the provided email address to ensure it's in a valid format
\nPublic Key Generation: The public key returned in the response is generated by Stripe and associated with the newly created account.
\nOnboarding URL Generation: The service requests a time-limited onboarding URL from Stripe, which is then returned in the response.
\nError Handling: The implementation lincludes comprehensive error handling to catch and appropriately respond to various error scenarios, both from internal processing and from the Stripe API.
\nThis endpoint is used to onboard connected accounts.
\naccount_id (string, required): The ID of the account to be onboarded.The response will contain the result of the onboarding process.
\n","urlObject":{"path":["api","v1","connected-accounts","onboarding"],"host":["https://commercecore-payment-api-bbdd0516ee91.herokuapp.com"],"query":[],"variable":[]}},"response":[{"id":"38cf856f-bdc2-4c4c-b8a7-ceb909696191","name":"Created Onboarding","originalRequest":{"method":"POST","header":[{"key":"X-Developer-Token","value":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI2OTM1NTA5LCJpYXQiOjE3MjY4NDkxMDksImp0aSI6IjQ3MmNkZjEzOTkzMjQ3ODdhYzE4MGExN2E0NWEzNmM5IiwidXNlcl9pZCI6InVzcl90M2hiWWlEbHh3RjBXUjZ6NDlGeW1WZ18yIiwiZGV2ZWxvcGVyX2lkIjoiZGVfOHZETC1MLWdBZjI0UnJBek1PZmdMQldoQSIsImFwcF9pZHMiOlsiYXBfM1BUTThMRlVjZmRsV19uakxwZmNTbUFKNiJdfQ.TUPaMsu2_296IheypiMiymoEkkDD4UCQ6um0JGqF3Us","type":"text","disabled":true},{"key":"X-Developer-Token","value":"The POST /api/v1/connected-accounts/login endpoint is used to log in to a connected account in the commercecore-payment-service. The request should include a JSON payload with the account_id field.
The response of this request follows the JSON schema below:
\n{\n \"type\": \"object\",\n \"properties\": {\n \"token\": {\n \"type\": \"string\"\n },\n \"expires_in\": {\n \"type\": \"integer\"\n }\n }\n}\n\nThe response object includes the token (a string) and expires_in (an integer) properties.
The Connected Accounts functionality in the CommerceCore Payment Microservice provides endpoints for managing and interacting with connected Stripe accounts. This feature is crucial for platforms that need to onboard sellers, service providers, or other entities that will receive payments through the platform.
\nEndpoint: POST /connected-accounts
This endpoint allows you to create a new connected account in Stripe.
\nX-Developer-Token: A developer token for authentication{\n \"email\": \"example@example.com\"\n}\n\n{\n \"data\": {\n \"account_id\": \"acct_xxxxxxxxxxxxxxxx\",\n \"public_key\": \"pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n \"message\": \"Connected account created successfully onboarding link expires in 18 hours use the 'onboarding_url' to complete the onboarding\"\n },\n \"meta\": {\n \"status_code\": 201\n },\n \"links\": {\n \"self\": https://commercecore-payment-api-bbdd0516ee91.herokuapp.com/api/v1/connected-accounts,\n \"onboarding_url\": \"https://connect.stripe.com/setup/e/acct_xxxxxxxxxxxxxxxx/xxxxxxxxxxxxxxxx\"\n }\n}\n\nEndpoint: POST /api/v1/connected-accounts/onboarding
This endpoint is used to initiate or continue the onboarding process for a connected account.
\nX-Developer-Token: A developer token for authentication{\n \"account_id\": \"acct_xxxxxxxxxxxxxxxx\"\n}\n\n{\n \"data\": {\n \"message\": \"Onboarding link expires in 13 hours use the 'onboarding_url' to complete the onboarding\"\n },\n \"meta\": {\n \"status_code\": 201\n },\n \"links\": {\n \"self\": https://commercecore-payment-api-bbdd0516ee91.herokuapp.com/api/v1/connected-accounts/onboarding,\n \"onboarding_url\": \"https://connect.stripe.com/setup/e/acct_1Q05C3FNeyusjZzz/j4wOPU7xxxxxxxxm4WzN\"\n }\n}\n\nEndpoint: POST /api/v1/connected-accounts/login
This endpoint generates a login link for the connected account's Stripe dashboard.
\n{\n \"account_id\": \"acct_xxxxxxxxxxxxxxxx\"\n}\n\nThe response will contain a login link for the Stripe dashboard. If the account has not completed onboarding, an error will be returned:
\n{\n \"detail\": \"An error occurred while creating the login link. Request req_xxxxxxxxxxxxxxxx: Cannot create a login link for an account that has not completed onboarding.\"\n}\n\nAuthentication: All endpoints require authentication, typically using a developer token provided in the X-Developer-Token header.
Onboarding Process: After creating a connected account, the account must complete the onboarding process before it can be fully utilized. The onboarding URL is provided in the response when creating a connected account.
\nLogin Link Expiration: The login link for the Stripe dashboard is temporary and will expire after a certain period.
\nError Handling: The API provides detailed error messages, which should be handled appropriately in your application.
\nAccount ID: The account_id is a crucial identifier for most operations related to connected accounts. It's provided when creating an account and should be stored for future use.
Public Key: Each connected account gets its own public key, which can be used for client-side operations specific to that account.
\nStripe Integration: This API appears to be a wrapper around Stripe's Connect API, simplifying the process of managing connected accounts within your platform.
\nThis contains the status and health of the api
\n","_postman_id":"98abed4a-fe6c-465a-82e0-753db607dce9"},{"name":"Transactions","item":[{"name":"Create Transaction","id":"a86a38b4-c638-468a-a8e1-ba498247d107","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-Developer-Token","value":"9080d9ea-a700-4eeb-9374-4034901e351e","type":"text"},{"key":"X-User-ID","value":"32e5a206-8aa5-49ab-b074-9d6a529cc42f","type":"text"},{"key":"X-App-ID","value":"6c9f4861-7e4e-4825-b636-c26430bb9220","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"order_id\":\"01922494-61b1-74e6-9d0c-0a04717d13e4\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://commercecore-payment-api-bbdd0516ee91.herokuapp.com/api/v1/transactions","urlObject":{"path":["api","v1","transactions"],"host":["https://commercecore-payment-api-bbdd0516ee91.herokuapp.com"],"query":[],"variable":[]}},"response":[{"id":"597886cd-13b0-40d0-a21a-e7f6f44598d2","name":"Initiated Transaction","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"order_id\": \"01922494-61b1-74e6-9d0c-0a04717d13e4\"\r\n}","options":{"raw":{"language":"json"}}},"url":"http://127.0.0.1:8000/api/v1/transactions"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"date","value":"Tue, 17 Sep 2024 23:28:17 GMT"},{"key":"server","value":"uvicorn"},{"key":"content-length","value":"302"},{"key":"content-type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"client_secret\": \"pi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxDESwtWsq\",\n \"status\": \"requires_payment_method\",\n \"transaction_id\": \"pi_3Q0AohFNeyusjZzz0MFRwI7M\"\n },\n \"meta\": {\n \"message\": \"Payment initiated successfully\",\n \"status_code\": 201\n },\n \"links\": {\n \"self\": \"http://127.0.0.1:8000/api/v1/transactions\"\n }\n}"},{"id":"f166f2ee-0059-49a5-8567-46f49537bba9","name":"Failure to Connect to Third Service","originalRequest":{"method":"POST","header":[{"key":"X-Developer-Token","value":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzI2OTM1NTA5LCJpYXQiOjE3MjY4NDkxMDksImp0aSI6IjQ3MmNkZjEzOTkzMjQ3ODdhYzE4MGExN2E0NWEzNmM5IiwidXNlcl9pZCI6InVzcl90M2hiWWlEbHh3RjBXUjZ6NDlGeW1WZ18yIiwiZGV2ZWxvcGVyX2lkIjoiZGVfOHZETC1MLWdBZjI0UnJBek1PZmdMQldoQSIsImFwcF9pZHMiOlsiYXBfM1BUTThMRlVjZmRsV19uakxwZmNTbUFKNiJdfQ.TUPaMsu2_296IheypiMiymoEkkDD4UCQ6um0JGqF3Us","type":"text"},{"key":"X-User-ID","value":"usr_t3hbYiDlxwF0WR6z49FymVg_2","type":"text"},{"key":"X-App-ID","value":"ap_3PTM8LFUcfdlW_njLpfcSmAJ6","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"order_id\": \"2227222\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://commercecore-payment-service.onrender.com/api/v1/transactions"},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Sat, 21 Sep 2024 14:13:15 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"180"},{"key":"Connection","value":"keep-alive"},{"key":"CF-Ray","value":"8c6aa79fbd6f0bc5-AMS"},{"key":"CF-Cache-Status","value":"DYNAMIC"},{"key":"Content-Encoding","value":"br"},{"key":"Vary","value":"Accept-Encoding"},{"key":"rndr-id","value":"8ef2a6b2-cd40-4427"},{"key":"x-render-origin-server","value":"uvicorn"},{"key":"Server","value":"cloudflare"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Internal Server Error\",\n \"meta\": {\n \"success\": false,\n \"status_code\": 500,\n \"request_method\": \"POST\",\n \"request_path\": \"https://commercecore-payment-service.onrender.com/api/v1/transactions\"\n },\n \"details\": {\n \"message\": \"All connection attempts failed\"\n }\n}"}],"_postman_id":"a86a38b4-c638-468a-a8e1-ba498247d107"},{"name":"Confirm Transaction","id":"ac02217a-803e-42e0-8504-87ec27c7a2bd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-Developer-Token","value":"9080d9ea-a700-4eeb-9374-4034901e351e","type":"text"},{"key":"X-User-ID","value":"32e5a206-8aa5-49ab-b074-9d6a529cc42f","type":"text"},{"key":"X-APP-ID","value":"6c9f4861-7e4e-4825-b636-c26430bb9220","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"payment_method_id\":\"pm_card_visa\",\r\n \"transaction_id\":\"pi_3QDm1PFWESP12sz21OLo3zE4\",\r\n \"account_id\": \"acct_1QDlglFLJMa7tjMS\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://commercecore-payment-api-bbdd0516ee91.herokuapp.com/api/v1/transactions/confirm","urlObject":{"path":["api","v1","transactions","confirm"],"host":["https://commercecore-payment-api-bbdd0516ee91.herokuapp.com"],"query":[],"variable":[]}},"response":[{"id":"3e820ec1-ccb1-48da-9895-8d05eac8067c","name":"Payment Already Confirmed","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"account_id\":\"acct_1Q05C3FNeyusjZzz\",\r\n \"payment_method_id\":\"pm_card_visa\",\r\n \"transaction_id\":\"pi_3Q0AohFNeyusjZzz0MFRwI7M\"\r\n}","options":{"raw":{"language":"json"}}},"url":"http://127.0.0.1:8000/api/v1/transactions/confirm"},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"json","header":[{"key":"date","value":"Wed, 18 Sep 2024 02:17:27 GMT"},{"key":"server","value":"uvicorn"},{"key":"content-length","value":"295"},{"key":"content-type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"detail\": \"An error occurred while confirming the payment intentRequest req_g66SutHWZA1AEi: You cannot confirm this PaymentIntent because it has already succeeded after being previously confirmed. Check if the payment method is valid, and also check if you havecompleted the onboarding process\"\n}"},{"id":"2e63f464-77e3-48ff-b785-2b4d4a28fd47","name":"Confirm Transaction","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"account_id\":\"acct_1Q05C3FNeyusjZzz\",\r\n \"payment_method_id\":\"pm_card_visa\",\r\n \"transaction_id\":\"pi_3Q1QX8FNeyusjZzz1P1mzgXX\"\r\n}","options":{"raw":{"language":"json"}}},"url":"http://127.0.0.1:8000/api/v1/transactions/confirm"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"date","value":"Sat, 21 Sep 2024 12:34:18 GMT"},{"key":"server","value":"uvicorn"},{"key":"content-length","value":"247"},{"key":"content-type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": {\n \"message\": \"Payment confirmed successfully\",\n \"status_code\": 200,\n \"account_id\": \"acct_xxxxxxxxxxxx\"\n },\n \"meta\": {\n \"message\": \"Payment confirmed successfully\",\n \"status_code\": 200\n },\n \"links\": {\n \"self\": \"http://127.0.0.1:8000/api/v1/transactions/confirm\"\n }\n}"},{"id":"fa030350-8381-495e-850a-3783a8d3da9b","name":"No account Id passed","originalRequest":{"method":"POST","header":[{"key":"X-Developer-Token","value":"This endpoint allows you to create a refund for a specific order.
\norder_id (string, required): The ID of the order for which the refund is being created.
account_id (string, required): The ID of the account to which the refund should be credited.
The response will include the status of the refund creation.
\n","urlObject":{"path":["api","v1","refunds"],"host":["https://commercecore-payment-api-bbdd0516ee91.herokuapp.com"],"query":[],"variable":[]}},"response":[{"id":"674dbf1c-f2e4-4ad3-bf1b-45daad1af4ca","name":"Provide App Id","originalRequest":{"method":"POST","header":[],"url":"http://127.0.0.1:8000/api/v1/refunds"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"date","value":"Tue, 17 Sep 2024 18:35:37 GMT"},{"key":"server","value":"uvicorn"},{"key":"content-length","value":"204"},{"key":"content-type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Bad Request\",\n \"meta\": {\n \"success\": false,\n \"status_code\": 400,\n \"request_method\": \"POST\",\n \"request_path\": \"http://127.0.0.1:8000/api/v1/refunds\"\n },\n \"details\": {\n \"message\": \"Provide app_id as a query parameter\"\n }\n}"},{"id":"43935f92-468a-4538-acf7-63965b486708","name":"Provide User Token","originalRequest":{"method":"POST","header":[],"url":{"raw":"http://127.0.0.1:8000/api/v1/refunds?app_id=ap_3PTM8LFUcfdlW_njLpfcSmAJ6","protocol":"http","host":["127","0","0","1"],"port":"8000","path":["api","v1","refunds"],"query":[{"key":"app_id","value":"ap_3PTM8LFUcfdlW_njLpfcSmAJ6"}]}},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"date","value":"Tue, 17 Sep 2024 18:43:23 GMT"},{"key":"server","value":"uvicorn"},{"key":"x-user-token","value":"Bearer"},{"key":"content-length","value":"60"},{"key":"content-type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"detail\": \"Please provide a valid user token in the header\"\n}"}],"_postman_id":"bd798a42-dbad-463b-a58a-26e9ae32f6ec"}],"id":"952185d7-94b6-4220-8bc1-f94e917ee9d0","_postman_id":"952185d7-94b6-4220-8bc1-f94e917ee9d0","description":""},{"name":"Payment Method","item":[{"name":"Create Payment Method","id":"e95b6805-3133-4be9-b6b7-b2c23d442264","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"X-User-ID","value":"7e84e1a5-5fd7-4ba0-9fa1-a4c74f2c8a60","type":"text"},{"key":"X-Developer-Token","value":"8659920e-245c-44ce-8269-3a696d90194f","type":"text"},{"key":"X-App-ID","value":"bf98189f-09d5-4a18-99b7-989e0a5ff96a","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"payment_method_id\":\"pm_card_visa\",\r\n \"type\": \"card\",\r\n \"preferred\":false\r\n}","options":{"raw":{"language":"json"}}},"url":"https://commercecore-payment-api-bbdd0516ee91.herokuapp.com/api/v1/payment-methods","urlObject":{"path":["api","v1","payment-methods"],"host":["https://commercecore-payment-api-bbdd0516ee91.herokuapp.com"],"query":[],"variable":[]}},"response":[],"_postman_id":"e95b6805-3133-4be9-b6b7-b2c23d442264"}],"id":"2b693fe9-c7d5-4010-be51-edb3ef3791bb","_postman_id":"2b693fe9-c7d5-4010-be51-edb3ef3791bb","description":""}],"id":"f6e8d1d7-ca24-4888-858d-a17c2744f1bd","description":"Version 1 of the CommerceCore Payment Microservice API provides a comprehensive set of endpoints for managing payment operations in e-commerce applications. This API is designed to work seamlessly with Stripe's payment infrastructure while offering additional features and abstractions tailored for the CommerceCore ecosystem.
\nKey features of Version 1 include:
\nManagement of Connected Accounts for multi-seller platforms
\nProcessing of transactions with a two-step (create and confirm) approach
\nHandling of refunds
\nSecure authentication and authorization mechanisms
\nComprehensive error reporting
\nThis version of the API is suitable for a wide range of e-commerce applications, from single-vendor stores to complex multi-seller marketplaces.
\nAll API requests should be made to the following base URL:
\nhttps://commercecore-payment-api-bbdd0516ee91.herokuapp.com/api/v1\n\nThe API uses a multi-layered authentication system to ensure security and proper attribution of actions. Different endpoints may require different combinations of the following authentication methods:
\nCopyX-Developer-Token:
\nCopyX-User-ID:
\nCopyX-App-ID:
\nEnsure that you include the required headers for each endpoint as specified in their individual documentation.
\nConnected Accounts allow platforms to create and manage Stripe accounts for their sellers or service providers. This feature is crucial for marketplaces and multi-seller platforms.
\nCreates a new Stripe Connected Account for a seller on your platform.
\nEndpoint: POST /connected-accounts
Authentication:
\nX-Developer-TokenRequest Body:
\n{\n \"email\": \"seller@example.com\"\n}\n\nResponse:
\n{\n \"data\": {\n \"account_id\": \"acct_1Q05C3FNeyusjZzz\",\n \"public_key\": \"pk_test_51PwVFgRoSQz2jDzeW3pxV97ssjskassdaeeaeeDuNBNLC......\",\n \"message\": \"Connected account created successfully onboarding link expires in 18 hours use the 'onboarding_url' to complete the onboarding\"\n },\n \"meta\": {\n \"status_code\": 201\n },\n \"links\": {\n \"self\": https://commercecore-payment-api-bbdd0516ee91.herokuapp.comapi/v1/connected-accounts,\n \"onboarding_url\": \"https://connect.stripe.com/setup/e/acct_1Q05C3FNeyusjZzz....\"\n }\n}\n\nStatus Codes:
\n201: Created successfully
\n401: Unauthorized (invalid or missing developer token)
\nImportant Notes:
\nThe onboarding_url in the response is crucial. Direct your seller to this URL to complete their account setup.
The onboarding link expires after 18 hours. Ensure your seller completes the process within this timeframe.
\nStore the account_id securely. You'll need it for future operations related to this seller.
Initiates or checks the status of the onboarding process for a connected account.
\nPlease note that accounts that have not yet completed onboarding will be restricted to
\ncertain level of transactions.
\nEndpoint: POST /connected-accounts/onboarding
Authentication:
\nX-Developer-TokenRequest Body:
\n{\n \"account_id\": \"acct_1Q05C3FNeyusjZzz\"\n}\n\nResponse:
The exact response format is not provided in the collection, but it typically includes:
The current status of the onboarding process
\nAny missing information required to complete onboarding
\nA new onboarding URL if the previous one has expired
\nGenerates a login link for a connected account's Stripe dashboard.
\nEndpoint: POST /connected-accounts/login
Authentication:
\nRequest Body:
\n{\n \"account_id\": \"acct_1Q05C3FNeyusjZzz\"\n}\n\nResponse:
\n{\n \"data\": {\n \"message\": \"Onboarding link expires in 13 hours use the 'onboarding_url' to complete the onboarding\"\n },\n \"meta\": {\n \"status_code\": 201\n },\n \"links\": {\n \"self\": \"http://127.0.0.1:8000/api/v1/connected-accounts/onboarding\",\n \"onboarding_url\": \"https://connect.stripe.com/setup/e/acct_1Q05C3FNeyusjZzz/j4wO\"\n }\n}\n\nStatus Codes:
\n201: Created successfully
\n401: Unauthorized (invalid or missing developer token)
\nStartFragment500: Internal Server Error (if account hasn't completed onboarding)
\nImportant Notes:
\nThe login link is temporary and should be used immediately.
\nThis feature allows sellers to access their own Stripe dashboard for detailed reporting and account management.
\nEnsure the account has completed onboarding before attempting to generate a login link.
\nThe Transactions endpoints handle the creation and confirmation of payments.
\nInitiates a new transaction (creates a PaymentIntent in Stripe terminology).
\nEndpoint: POST /transactions
Authentication:
\nX-Developer-Token, X-User-ID, X-App-IDRequest Body:
\n{\n \"order_id\": \"2227222\",\n \"account_id\": \"acct_xxxxxxxxxxxx\",\n \"amount\": \"1000\"\n}\n\nResponse:
\n{\n \"data\"\",\n \"status\": \"requires_payment_method\",\n \"transaction_id\": \"pi_xxxxxxxxxxxxxxxxxx\"\n },\n \"meta\": {\n \"message\": \"Payment initiated successfully\",\n \"status_code\": 201\n },\n \"links\": {\n \"self\": https://commercecore-payment-api-bbdd0516ee91.herokuapp.com/api/v1/transactions\n }\n}\n\nStatus Codes:
\nImportant Notes:
\nThe amount is in the smallest currency unit (e.g., cents for USD).
The client_secret is crucial for completing the payment on the client-side. Handle it securely.
The transaction_id (Stripe's PaymentIntent ID) is needed for the confirmation step.
if you don't know how to use stripe client read more on that
\nConfirms a previously initiated transaction after the customer has provided payment details.
\nEndpoint: POST /transactions/confirm
Request Body:
\n{\n \"account_id\": \"acct_1Q05C3FNeyusjZzz\",\n \"payment_method_id\": \"pm_card_visa\",\n \"transaction_id\": \"pi_3Q1JMrFNeyusjZzz1RxOU8wm\"\n}\n\nResponse:
\n{\n \"data\": {\n \"message\": \"Payment confirmed successfully\",\n \"status_code\": 200,\n \"account_id\": \"acct_1Q05C3F21133\"\n },\n \"meta\": {\n \"message\": \"Payment confirmed successfully\",\n \"status_code\": 200\n },\n \"links\": {\n \"self\": https://commercecore-payment-api-bbdd0516ee91.herokuapp.com/api/v1/transactions/confirm\n }\n}\n\nTypically includes:
\nStatus Codes:
\n500: Internal Server Error (if payment has already been confirmed)
\n201: Created successfully
\nImportant Notes:
\nOnly confirm a transaction once. Attempting to confirm an already confirmed transaction will result in an error.
\nThe payment_method_id should be obtained from the client-side after the customer enters their payment details.
The Refunds endpoint allows you to process refunds for completed transactions.
\nInitiates a refund for a previously completed transaction.
\nEndpoint: POST /refunds
Authentication:
\nX-User-ID, X-Developer-Token, X-App-IDRequest Body:
\n{\n \"order_id\": \"2227222\",\n \"account_id\": \"acct_1Q05C3FNeyusjZzz\"\n}\n\nResponse:
The exact response format is not provided in the collection, but it typically includes:
The status of the refund request
\nThe refunded amount
\nA refund ID for future reference
\nStatus Codes:
\n400: Bad Request (if app_id is not provided)
\n401: Unauthorized (if user token is not provided)
\nImportant Notes:
\nEnsure that the order_id corresponds to a completed transaction.
Refunds are typically processed asynchronously. Your application should be prepared to handle webhook events for refund updates.
\nPartial refunds may be supported, though the current documentation doesn't specify this feature.
\nThe API uses standard HTTP status codes to indicate the success or failure of requests. In case of errors, the API returns a JSON object with details about the error.
\nExample error response:
\njsonCopy{\n \"error\": \"Bad Request\",\n \"meta\": {\n \"success\": false,\n \"status_code\": 400,\n \"request_method\": \"POST\",\n \"request_path\": https://commercecore-payment-api-bbdd0516ee91.herokuapp.com/api/v1/refunds\n },\n \"details\": {\n \"message\": \"Provide app_id in the header\"\n }\n}\n\nCommon error scenarios to handle in your application:
\n400 Bad Request: Check your request parameters and body
\n401 Unauthorized: Verify your authentication credentials
\n404 Not Found: Ensure you're using the correct endpoint and resource IDs
\n500 Internal Server Error: Contact CommerceCore support if this persists
\nImplement exponential backoff in case of rate limit errors
\nCache responses where appropriate to reduce the number of API calls
\nPayment succeeded
\nPayment failed
\nRefund processed
\nAccount updated
\nImplement a webhook endpoint in your application and register it with CommerceCore to receive real-time updates.
\nThe collection includes a test payment method (pm_card_visa) which can be used for testing transactions in a sandbox environment.
Best practices for testing:
\nUse Stripe's test card numbers for various scenarios (successful payments, declined cards, etc.)
\nTest the entire payment flow, including refunds
\nVerify webhook handling with test events
\nTo test with more stripe cards visit stripe.com
\nAlways use test credentials and test card numbers when working in non-production environments.
\n","_postman_id":"f6e8d1d7-ca24-4888-858d-a17c2744f1bd"}],"event":[{"listen":"prerequest","script":{"id":"c7f018d6-81a6-4d01-b388-6a9b6f61522c","type":"text/javascript","packages":{},"exec":[""]}},{"listen":"test","script":{"id":"6e879024-c0fa-4f88-b254-22d4e4b20410","type":"text/javascript","packages":{},"exec":[""]}}],"variable":[{"key":"base_url","value":"https://commercecore-payment-api-bbdd0516ee91.herokuapp.com","type":"string"}]}