--- updatedAt: 2025-07-14T12:33:41.000Z agentTools: projectIndex: https://docs.getpinch.com.au/llms.txt --- # Create Realtime Payment Take credit card payments with a realtime response. ## Failed Payments When a payment fails, the dishonour property will contain a dishonour object. You can find more information about the failure codes here: [Dishonour Codes](https://docs.getpinch.com.au/docs/dishonour-codes) # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "pinch-api-payments", "version": "2020.1" }, "servers": [ { "url": "https://api.getpinch.com.au/test" } ], "components": { "securitySchemes": { "sec0": { "type": "oauth2", "flows": {} } } }, "security": [ { "sec0": [] } ], "paths": { "/payments/realtime": { "post": { "summary": "Create Realtime Payment", "description": "", "operationId": "realtime-payment", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "payerId": { "type": "string", "description": "The Payer ID to use, if you're executing this payment against an existing payer." }, "fullName": { "type": "string", "description": "Use Full Name, or First Name and Last Name" }, "firstName": { "type": "string", "description": "Use Full Name, or First Name and Last Name" }, "lastName": { "type": "string", "description": "Use Full Name, or First Name and Last Name" }, "email": { "type": "string", "description": "The email address of the payer" }, "mobileNumber": { "type": "string", "description": "A non-international Australian 10-digit mobile number" }, "amount": { "type": "integer", "description": "The payment amount in cents", "format": "int32" }, "applicationFee": { "type": "integer", "description": "Optional additional fee (in cents) that goes to the parent merchant (Managed Merchants Only)", "format": "int32" }, "description": { "type": "string", "description": "An optional description for the payment. Will be visible to the payer. Must be less than 1000 characters." }, "sourceId": { "type": "string", "description": "Specify an existing payment source to use for this transaction. If empty, the default will be used. If you are creating a new source, use the creditCardToken field instead." }, "token": { "type": "string", "description": "The credit card or bank account token created by the capture script. See the Guide for more info." }, "surcharge": { "type": "array", "description": "A list of source types to surcharge (Pass on the fees to the customer). eg. ['bank-account', 'credit-card']", "items": { "type": "string" } }, "nonce": { "type": "array", "description": "Optional. A nonce is a one-time-use reference that represents a unique payment. Used to prevent double submissions of payments. If left empty all submissions will be treated as unique. Can be a string or array of strings. Each nonce must not exceed 250 characters and the length of all nonces must not exceed 4000 characters.", "items": { "type": "string" } }, "metadata": { "type": "string", "description": "Free text field that you can use to store state against certain entities. Can be used for accounting integration, see [Metadata](https://docs.getpinch.com.au/docs/metadata)" } }, "required": [ "amount" ] }, "examples": { "Request Example": { "value": { "fullName": "Ben Hotdog", "email": "ben.hotdog@mailinator.com", "amount": "1245", "description": "A sweet new hat", "token": "tkn_dk9GpnBk2vIlSbxsOZ8Vk0FwCQBVeABk" } } } } } }, "responses": { "201": { "description": "201", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"id\": \"pmt_XXXXXXXXXXXXXX\",\n \"attemptId\": \"att_XXXXXXXX\",\n \"amount\": 1245,\n \"currency\": \"AUD\",\n \"description\": \"A sweet new hat\",\n \"applicationFee\": 0,\n \"totalFee\": 61,\n \"isSurcharged\": false,\n \"sourceType\": \"credit-card\",\n \"transactionDate\": \"2021-04-19T05:20:54.4601157Z\",\n \"status\": \"approved\",\n \"estimatedTransferDate\": \"2021-04-21\",\n \"actualTransferDate\": null,\n \"payer\": {\n \"id\": \"pyr_XXXXXXXXXXXXXX\",\n \"firstName\": \"Ben\",\n \"lastName\": \"Hotdog\",\n \"emailAddress\": \"ben.hotdog@mailinator.com\",\n \"mobileNumber\": null,\n \"streetAddress\": null,\n \"suburb\": null,\n \"postcode\": null,\n \"state\": null,\n \"country\": null,\n \"companyName\": null,\n \"companyRegistrationNumber\": null,\n \"metadata\": null\n },\n \"subscription\": null,\n \"attempts\": [\n {\n \"id\": \"att_XXXXXXXX\",\n \"amount\": 1245,\n \"currency\": \"AUD\",\n \"convertedAmount\": null,\n \"conversionRate\": null,\n \"convertedCurrency\": null,\n \"estimatedSettlementDate\": \"2021-04-21T00:00:00\",\n \"isSurcharged\": false,\n \"transactionDate\": \"2021-04-19T05:20:54.4601157Z\",\n \"estimatedTransferDate\": \"2021-04-21\",\n \"actualTransferDate\": null,\n \"source\": {\n \"id\": \"src_XXXXXXXXXXXXXX\",\n \"sourceType\": \"credit-card\",\n \"bankAccountNumber\": null,\n \"bankAccountBsb\": null,\n \"bankAccountName\": null,\n \"creditCardToken\": \"tkn_XXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\n \"cardHolderName\": \"Ben Hotdog\",\n \"expiryDate\": \"2022-12-01T00:00:00\",\n \"displayCardNumber\": \"4242\",\n \"cardScheme\": \"visa\",\n \"origin\": \"AU\"\n },\n \"dishonour\": null,\n \"settlement\": null,\n \"fees\": {\n \"transactionFee\": 61,\n \"applicationFee\": 0,\n \"totalFee\": 61,\n \"currency\": \"AUD\",\n \"taxRate\": 0.1,\n \"convertedTransactionFee\": null,\n \"convertedApplicationFee\": null,\n \"convertedTotalFee\": null,\n \"convertedCurrency\": null,\n \"conversionRate\": null\n },\n \"status\": \"approved\"\n }\n ],\n \"metadata\": null\n}" } }, "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "pmt_XXXXXXXXXXXXXX" }, "attemptId": { "type": "string", "example": "att_XXXXXXXX" }, "amount": { "type": "integer", "example": 1245 }, "currency": { "type": "string", "example": "AUD" }, "description": { "type": "string", "example": "A sweet new hat" }, "applicationFee": { "type": "integer", "example": 0 }, "totalFee": { "type": "integer", "example": 61 }, "isSurcharged": { "type": "boolean", "example": false }, "sourceType": { "type": "string", "example": "credit-card" }, "transactionDate": { "type": "string", "example": "2021-04-19T05:20:54.4601157Z" }, "status": { "type": "string", "example": "approved" }, "estimatedTransferDate": { "type": "string", "example": "2021-04-21" }, "actualTransferDate": {}, "payer": { "type": "object", "properties": { "id": { "type": "string", "example": "pyr_XXXXXXXXXXXXXX" }, "firstName": { "type": "string", "example": "Ben" }, "lastName": { "type": "string", "example": "Hotdog" }, "emailAddress": { "type": "string", "example": "ben.hotdog@mailinator.com" }, "mobileNumber": {}, "streetAddress": {}, "suburb": {}, "postcode": {}, "state": {}, "country": {}, "companyName": {}, "companyRegistrationNumber": {}, "metadata": {} } }, "subscription": {}, "attempts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "att_XXXXXXXX" }, "amount": { "type": "integer", "example": 1245 }, "currency": { "type": "string", "example": "AUD" }, "convertedAmount": {}, "conversionRate": {}, "convertedCurrency": {}, "estimatedSettlementDate": { "type": "string", "example": "2021-04-21T00:00:00" }, "isSurcharged": { "type": "boolean", "example": false }, "transactionDate": { "type": "string", "example": "2021-04-19T05:20:54.4601157Z" }, "estimatedTransferDate": { "type": "string", "example": "2021-04-21" }, "actualTransferDate": {}, "source": { "type": "object", "properties": { "id": { "type": "string", "example": "src_XXXXXXXXXXXXXX" }, "sourceType": { "type": "string", "example": "credit-card" }, "bankAccountNumber": {}, "bankAccountBsb": {}, "bankAccountName": {}, "creditCardToken": { "type": "string", "example": "tkn_XXXXXXXXXXXXXXXXXXXXXXXXXXXX" }, "cardHolderName": { "type": "string", "example": "Ben Hotdog" }, "expiryDate": { "type": "string", "example": "2022-12-01T00:00:00" }, "displayCardNumber": { "type": "string", "example": "4242" }, "cardScheme": { "type": "string", "example": "visa" }, "origin": { "type": "string", "example": "AU" } } }, "dishonour": {}, "settlement": {}, "fees": { "type": "object", "properties": { "transactionFee": { "type": "integer", "example": 61 }, "applicationFee": { "type": "integer", "example": 0 }, "totalFee": { "type": "integer", "example": 61 }, "currency": { "type": "string", "example": "AUD" }, "taxRate": { "type": "number", "example": 0.1 }, "convertedTransactionFee": {}, "convertedApplicationFee": {}, "convertedTotalFee": {}, "convertedCurrency": {}, "conversionRate": {} } }, "status": { "type": "string", "example": "approved" } } } }, "metadata": {} } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{}" } }, "schema": { "type": "object", "properties": {} } } } } }, "deprecated": false, "x-readme": { "code-samples": [ { "language": "csharp", "code": "var result = await api.Payment.ExecuteRealtime(new RealtimePaymentSaveOptions()\n{\n FullName = \"Ben Hotdog\",\n Email = \"ben.hotdog@mailinator.com\",\n Token = \"tkn_b78d0293rn798ydb9287e6t7f987b3\",\n Amount = 1245, \n Description = \"A sweet new hat\",\n \tSurcharge = new List() \n {\n \"bank-account\",\n \"credit-card\"\n }\n});" }, { "language": "curl", "code": "curl https://api.getpinch.com.au/test/payments/realtime \n -H \"Authorization: Bearer ...\" \n -H \"Content-Type: application/json\" \n -d \"{\n 'fullName': 'Ben Hotdog',\n 'email': 'ben.hotdog@mailinator.com',\n 'amount': 1245,\n 'description': 'A sweet new hat',\n 'token': 'tkn_dk9GpnBk2vIlSbxsOZ8Vk0FwCQBVeABk'\n}\"" } ], "samples-languages": [ "csharp", "curl" ] } } } }, "x-readme": { "headers": [ { "key": "pinch-version", "value": "2020.1" } ], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```