### Response Sample for Get Payment Methods Source: https://developer.secuconnect.com/api Example response showing available payment methods for a contract. ```json [ "Applepay", "Creditcard", "Debit", "easyCredit", "Googlepay", "Invoice", "MC pay by bank", "Paypal", "Prepay" ] ``` -------------------------------- ### POST /payment/init Request Example Source: https://developer.secuconnect.com/integration/Create_Payment_Transaction.html This is an example of the POST request body required to create a new payment transaction. Ensure all required fields, such as apikey, payment_type, and amount, are correctly populated. ```json { "data": { "apikey": "6801fxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ace", "payment_type": "debit", "demo": 1, "payment_action": "sale", "url_success": "https://example.org/SUCCESS", "url_failure": "https://example.org/FAILURE", "url_push": "https://example.org/PUSH", "apiversion": "2.11", "language": "de_DE", "title": "Herr", "firstname": "Max", "lastname": "Mustermann", "street": "Musterstr.", "housenumber": "112 a", "zip": "09555", "city": "Musterhausen", "country": "DE", "telephone": "+4912342134123", "dob_value": "01.02.1903", "email": "max@example.org", "ip": "172.31.6.49", "currency": "EUR", "amount": "199", "purpose": "Test order 1" } } ``` -------------------------------- ### Pre-Transaction Response Example Source: https://developer.secuconnect.com/integration/Step_3__Apply_the_Loyalty_Card_for_Payment.html This is an example of a successful response when applying a loyalty card. The 'missing_sum' indicates the remaining amount to be paid in the smallest currency unit. ```json HTTP/1.1 200 OK Content-Type: application/json ... { "missing_sum": 296, "bonus_products": [] } ``` -------------------------------- ### Example Request with Shipping Fee Source: https://developer.secuconnect.com/integration/Pass_Shipping_Fee.html This example demonstrates how to add a shipping fee to the basket in a transaction initiation request. The shipping fee is included as a separate item in the basket array. ```json POST /payment/init HTTP/1.1 Host: api-testing.secuconnect.com Content-Type: application/json; charset=utf-8; Accept: application/json Accept-Charset: utf-8 { "data": { "apikey": "6801fxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ace", "payment_type": "debit", ... "currency": "EUR", "amount": "12485", "basket": [ { "item_type": "article", "article_number": "4124", "quantity": "2", "name": "Book shelf Peter, 201 x 59 x 28", "ean": "4123412341243", "tax": "19", "total": "11990", "price": "5995" }, { "item_type": "shipping", "name": "standard delivery", "tax": "19", "total": "495" } ] } } } ``` -------------------------------- ### Example Payment Initialization Request Source: https://developer.secuconnect.com/integration/Pass_Shop_Module_Information.html Demonstrates a POST request to /payment/init including shop and module version details. Use this for passing shop-specific information. ```http POST /payment/init HTTP/1.1 Host: api-testing.secuconnect.com Content-Type: application/json; charset=utf-8; Accept: application/json Accept-Charset: utf-8 { "data": { "apikey": "6801fxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ace", "payment_type": "debit", "demo": 1, ... "shop": "APITest Shop", "shopversion": "1.0", "moduleversion": "1.0", ... } } ``` -------------------------------- ### POST /payment/init Request with Customer Experience Source: https://developer.secuconnect.com/integration/Improve_Customer_Rating.html This example demonstrates how to include customer ID and experience data (positive and negative) in a POST request to initialize a payment. Ensure your contract has the necessary options enabled by customer service. ```http POST /payment/init HTTP/1.1 Host: api-testing.secuconnect.com Content-Type: application/json; charset=utf-8; Accept: application/json Accept-Charset: utf-8 { "data":{ "apikey": "6801fxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ace", "payment_type": "debit", "demo": 1, "currency": "EUR", "amount": "15900", "purpose": "Test order 1", ... "merchant_customer_id": "1234", "experience": { "positive": "1", "negative": "0" } } } ``` -------------------------------- ### Get Card Balance Receipt - Request Payload Source: https://developer.secuconnect.com/api Example JSON payload for requesting a card balance receipt. Requires the card number and terminal ID. ```json { "cardnumber": "9276004524764102", "terminal_id": 0 } ``` -------------------------------- ### Read Payment Transaction Response Source: https://developer.secuconnect.com/integration/Payment_Transaction_Status.html This is an example response when reading an entire payment transaction using the `GET /api/v2/Payment/Transactions/PCI_xyz` endpoint. Use the fields within the `details` object for status information. ```json { "object": "payment.transactions", "id": "PCI_WMC2TN4PT66CY90TS8YZY34QK9W2N7", // ... "amount": 1000, "currency": "EUR", // ... "status": 103, "status_text": "teilausgezahlt (Gutschrift beglichen)", "details": { // ... "status": 103, "status_text": "teilausgezahlt (Gutschrift beglichen)", "status_simple": 1, "status_simple_text": "accepted", // ... }, // ... } ``` -------------------------------- ### Read Smart Transaction API Request Source: https://developer.secuconnect.com/integration/Integrate_Smart_Checkout_for_Platforms.html This is an example of an HTTP GET request to retrieve the details of a Smart Transaction using its ID. Ensure the Host and Authorization headers are correctly set. ```http GET /v2/Smart/Transactions/STX_2AUSR7M6B2NHPG3C4JTKBEY07YXSAZ HTTP/1.1 Host: connect-testing.secuconnect.com Authorization: Bearer qb56tjj1bcvo9n2nj4u38k84lo Accept: application/json ``` -------------------------------- ### JSON Response Sample (200 OK) Source: https://developer.secuconnect.com/api Example of a successful JSON response for a Smart Device configuration request. ```json { "merchant": { "id": "MRC_FMP885SKMIQ6LTZ014C9GA7NKQIP2K", "auth_password_set": false }, "store": { "id": "STO_YPPAYAHBK0I9SYDWEHBFQEESTOVBP5", "auth_password_set": false }, "smart_device": { "id": "SDV_F7T8R23B2P7RVAR5WQWVNP689Z9QTH", "auth_password_set": true } } ``` -------------------------------- ### Payment Capture Response Source: https://developer.secuconnect.com/integration/Authorise_and_Capture_the_Payment3.html Example response after starting the Smart Transaction to capture the payment. The Smart Transaction status is updated to 'ok', and the Subscription object's status changes from 'approved' to 'active'. ```JSON HTTP/1.1 200 OK Content-Type: application/json ... { "object": "smart.transactions", "id": "STX_33PXAW2YN2NJTPM5KPGMK7QF5PBVA2", // ... "transactions": [ { "object": "payment.transactions", "id": "PCI_FDBREW9ZS7P6FTN4ZY2ATC6NK0QWO7" } ], // ... "updated_at": "2020-03-27T10:56:41+01:00", "status": "ok", // ... } ``` -------------------------------- ### Example Request with Merchant Information Source: https://developer.secuconnect.com/integration/Pass_Merchant_Information.html Demonstrates how to include optional merchant-specific data such as customer ID, order ID, and user fields in a POST /payment/init request. ```http POST /payment/init HTTP/1.1 Host: api-testing.secuconnect.com Content-Type: application/json; charset=utf-8; Accept: application/json Accept-Charset: utf-8 { "data": { "apikey": "6801fxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ace", "payment_type": "debit", ... "merchant_customer_id": "1234", "order_id": "100203", "userfield_1": "Hotel room, 1 person, bed and breakfast", "userfield_2": "person is walking disabled; arrival at about 9 p. m.", "userfield_3": "2020/01/28 through 2020/01/30" } } ``` -------------------------------- ### Receipt Separator Line Example Source: https://developer.secuconnect.com/integration/Authorise_and_Capture_the_Payment.html This JSON snippet shows a 'separator' type receipt line, used to start a new section with an optional caption. It is typically centered, bold, and larger than normal text. ```json { "type": "separator", "value": { "caption": "Kundenkarte Aufladung" } } ``` ```json { "type": "separator", "value": { } } ``` -------------------------------- ### Smart Device Creation Response Sample Source: https://developer.secuconnect.com/api This is a sample JSON response after successfully creating a smart device. It returns the details of the newly created device. ```json { "object": "smart.devices", "id": "SDV_F7T8R23B2P7RVAR5WQWVNP689Z9QTH", "merchant": { "object": "general.merchants", "id": "MRC_FMP885SKMIQ6LTZ014C9GA7NKQIP2K" }, "store": { "object": "general.stores", "id": "STO_YPPAYAHBK0I9SYDWEHBFQEESTOVBP5", "name": "Shop name", "name_raw": "Raw shop name" }, "vendor": "apidevices", "vendor_uid": "/uuid/xxxxxxxxxxxx", "type": "cashier", "description": null, "status": "active", "created": "2024-03-15T10:00:00+01:00", "updated": "2024-03-15T10:00:00+01:00", "refresh": 0, "connection_type": null } ``` -------------------------------- ### Install Java SDK using Maven Source: https://developer.secuconnect.com/integration/Java_SDK.html Run this command in your project directory after adding the Maven dependency to install the SDK. ```bash mvn install ``` -------------------------------- ### Payment Contract Request Payload Example Source: https://developer.secuconnect.com/api This is a generic example of a payment contract request payload. It includes essential contact and payout information. ```json { "contact": { "salutation": "Mr.", "title": "Dr.", "forename": "Max", "surname": "Mustermann", "companyname": "Musterfirma GmbH", "dob": "1981-02-03", "email": "muster@example.com", "phone": "+49 555 5555555", "mobile": "+49 170 5555555", "address": { "street": "Musterstr.", "street_number": "1a", "postal_code": "09999", "city": "Musterstadt", "country": "DE" } }, "project": "Erlebnis-Bauernhof Musterdorf", "payout_account": { "iban": "DE02120300000000202051", "owner": "Musterfirma GmbH" } } ``` -------------------------------- ### Example Query String with Wildcards and Ranges Source: https://developer.secuconnect.com/api Demonstrates advanced query string syntax including wildcards, value ranges, logical operators (AND, OR, NOT), and parenthesis for precedence. ```text (NOT customer.name:meier*) AND (customer.age:[30 TO 40] OR customer.age:[50 TO 60]) ``` -------------------------------- ### JSON Response Sample (Smart Device Apps) Source: https://developer.secuconnect.com/api Example of a JSON response detailing the apps configured for a Smart Device. ```json { "apps": [ { "app_id": "APP_D2T3Q24B2P7RVAR5WSWVNP689Z9QTH", "app_name": "Loyalty", "version": "0.2.1", "url": "https://connect.secuconnect.com/connect/secubase/fetchApp/name/loyalty/version/0.2.1", "etag": "fsgkpduw9nw9siusowesfi30eamo70jr", "prio": 10 } ] } ``` -------------------------------- ### Pre-Transaction Response Example Source: https://developer.secuconnect.com/integration/Apply_the_Loyalty_Card_for_Payment.html This is an example response after calling the preTransaction endpoint. It indicates the remaining amount to be paid ('missing_sum') and any bonus products collected. ```json { "missing_sum": 296, "bonus_products": [] } ``` -------------------------------- ### Example Positive Push Notification Acknowledgment Source: https://developer.secuconnect.com/integration/Status_Notifications_%28Push_API%29.html Example HTTP response to acknowledge a received push notification successfully. Return 'ack=Approved' to confirm processing. ```http HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded ack=Approved&hash=bogushashval1524&status_id=6&status_description=abgeschlossen&changed=1365444092&payment_status=accepted&apikey=6801fxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ace ``` -------------------------------- ### Payment Initialization Request with Return URLs Source: https://developer.secuconnect.com/integration/Define_Return_URLs.html Example of a POST request to `/payment/init` including `url_success` and `url_failure` parameters. These URLs are used to redirect customers after a transaction. ```json POST /payment/init HTTP/1.1 Host: api-testing.secuconnect.com Content-Type: application/json; charset=utf-8; Accept: application/json Accept-Charset: utf-8 { "data": { "apikey": "6801fxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ace", "payment_type": "debit", "demo": 1, "url_success": "http://shop.example.com/success.php", "url_failure": "http://shop.example.com/failure.php", ... } } ``` -------------------------------- ### Example Push Notification Request Source: https://developer.secuconnect.com/integration/Status_Notifications_%28Push_API%29.html An example of the POST request your server will receive from secuconnect containing payment status details. The content type is application/x-www-form-urlencoded. ```http POST /push_client.php HTTP/1.1 Host: push.example.org Content-Type: application/x-www-form-urlencoded Accept: */* hash=tujevzgobryk3303&status_id=6&status_description=abgeschlossen&changed=1365444092&payment_status=accepted&apikey=6801fxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ace ``` -------------------------------- ### POST /payment/init Request with Payment Hint Source: https://developer.secuconnect.com/integration/Show_Payment_Hint.html This snippet demonstrates a POST request to the /payment/init endpoint, including the 'payment_hint' field. Use this to display detailed payment information in a formatted manner. ```json POST /payment/init HTTP/1.1 Host: api-testing.secuconnect.com Content-Type: application/json; charset=utf-8; Accept: application/json Accept-Charset: utf-8 { "data": { "apikey": "6801fxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ace", "payment_type": "debit", "demo": 1, ... "currency": "EUR", "amount": "45000", "purpose": "Restzahlung 500016251 Mustermann Warnemünde 5.-10.9.2020", "order_id": "500016251", "language": "de_DE", "payment_hint": [ { "item": "Verwendungszweck:", "hint": "Restzahlung Ferienwohnung" }, { "item": "Bestellnumer:", "hint": "500016251" }, { "item": "Zeitraum:", "hint": "5.-10.9.2020" }, { "item": "Ferienwohung", "hint": "Warnemünde, Appartment \"Meerblick\", bis 5 P." } ], "labels": { "de_DE": { "payment_hint_title": "Details zu Ihrem Auftrag" } } } } ``` -------------------------------- ### Create Smart Routing Response Sample Source: https://developer.secuconnect.com/api Example JSON response after successfully creating a Smart Routing. ```json { "object": "smart.routings", "id": "SRT_8ISKYZGZ9BXUMZ3LF4VIA4ZAA26NIO", "merchant": { "object": "general.merchants", "id": "MRC_XTWA9BI8TJU5JUOAOSZAL7WG0L9A7B", "parent": { "object": "general.merchants", "id": "MRC_DJ71CC369Z10T15WAQ5NJG9OONOK0M", "type": 16 } }, "store": { "object": "general.stores", "id": "STO_YPPAYAHBK0I9SYDWEHBFQEESTOVBP5", "name": "Store im Mustercenter" }, "created": "2024-03-15T10:00:00+01:00", "updated": "2024-03-15T10:00:00+01:00", "description": "Kasse 3" } ``` -------------------------------- ### GET /Prepaid/Reports/{prepaidReportsId} Source: https://developer.secuconnect.com/api Retrieves a specific Prepaid Report using its unique ID. This endpoint allows for expanding fields to get more detailed information. ```APIDOC ## GET /Prepaid/Reports/{prepaidReportsId} ### Description Retrieves the specified Prepaid Report. Requires the Prepaid Report ID as a path parameter. An optional 'expand' query parameter can be used to include additional fields in the response. ### Method GET ### Endpoint /api/v2/Prepaid/Reports/{prepaidReportsId} ### Parameters #### Path Parameters - **prepaidReportsId** (string) - Required - Prepaid Reports ID #### Query Parameters - **expand** (string) - Optional - Example: expand=true. Expand fields (all or a specific one). ### Response #### Success Response (200) Prepaid Report details. #### Error Responses - **401** - Missing or invalid token - **403** - Not logged in or no contract - **404** - Resource not found or no permission - **500** - Validation errors, etc. - **default** - Other errors ``` -------------------------------- ### Example Request with Delivery Address Source: https://developer.secuconnect.com/integration/Pass_Delivery_Address.html This snippet shows a sample POST request to initiate a payment, including customer details and a distinct delivery address. Use this when the delivery location differs from the customer's primary address. ```json POST /payment/init HTTP/1.1 Host: api-testing.secuconnect.com Content-Type: application/json; charset=utf-8; Accept: application/json Accept-Charset: utf-8 { "data": { "apikey": "6801fxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx7ace", "payment_type": "debit", "demo": 1, ... "title": "Herr", "firstname": "Max", "lastname": "Mustermann", "street": "Musterstr.", "housenumber": "112 a", "zip": "09555", "city": "Musterhausen", "country": "DE", "telephone": "+4912342134123", "dob_value": "01.02.1903", "email": "max@example.org", ... "delivery_address": { "firstname": "Max", "lastname": "Mustermann", "street": "Gartenstr.", "housenumber": "22", "zip": "90555", "city": "Musterdorf", "country": "DE" } } } ``` -------------------------------- ### Create Smart Transaction with Delivery Details Source: https://developer.secuconnect.com/integration/Delivery_Details_of_an_Order.html This example demonstrates how to create a Smart Transaction and include initial delivery options, such as the delivery type. ```APIDOC ## POST /api/v2/Smart/Transactions ### Description Creates a Smart Transaction and allows specifying delivery options like the delivery type. ### Method POST ### Endpoint /api/v2/Smart/Transactions ### Request Body - **delivery_options** (object) - Optional - Contains details about the delivery. - **type** (string) - Required - Specifies the type of delivery (e.g., "shipping"). ### Request Example ```json { "// ...": "// Other transaction details", "delivery_options": { "type": "shipping" } } ``` ### Response #### Success Response (200 OK) Returns the created Smart Transaction object with updated delivery details. - **object** (string) - The type of the object, e.g., "smart.transactions". - **id** (string) - The unique identifier for the Smart Transaction. - **delivery_options** (object) - Contains details about the delivery. - **type** (string) - The type of delivery. - **shipped_at** (null) - Placeholder for the shipping timestamp. - **shipped_by** (null) - Placeholder for who shipped the order. - **tracking_code** (null) - Placeholder for the tracking code. - **invoice_number** (null) - Placeholder for the invoice number. #### Response Example ```json { "object": "smart.transactions", "id": "STX_WNUPCCR822NTDB0PP9A0E3FPYEANA2", "// ...": "// Other transaction details", "delivery_options": { "type": "shipping", "shipped_at": null, "shipped_by": null, "tracking_code": null, "invoice_number": null }, "// ...": "// Other transaction details" } ``` ``` -------------------------------- ### Loyalty Transaction Response Example Source: https://developer.secuconnect.com/integration/Authorise_and_Capture_the_Payment.html This is an example of a successful response (HTTP 200 OK) after executing a loyalty transaction. It includes details about the transaction, basket, and receipt. ```JSON HTTP/1.1 200 OK Content-Type: application/json ... { "object": "smart.transactions", "id": "STX_3QPGBB72F2NSPDS95JZPWA772DUMAZ", // ... "status": "ok", // ... "basket": { "products": [{ "id": 1, "parent": null, "articleNumber": "30037", "ean": "", "desc": "Sandwich Romano", "quantity": 1, "priceOne": 349, "tax": 7, "group": [], "serialNumber": null, "item_type": "article", "reference_id": null, "contract_id": null, "sum": null }, { "id": 2, "parent": null, "articleNumber": "30200", "ean": "", "desc": "Fruit salad, small bowl", "quantity": 1, "priceOne": 249, "tax": 7, "group": [], "serialNumber": null, "item_type": "article", "reference_id": null, "contract_id": null, "sum": null }, { "id": 3, "parent": null, "articleNumber": "51", "ean": "4999012345678", "desc": "Water, mildly sprinkling, 0.25 ltr.", "quantity": 2, "priceOne": 99, "tax": 19, "group": [], "serialNumber": null, "item_type": "article", "reference_id": null, "contract_id": null, "sum": null }, { "id": 4, "parent": null, "articleNumber": "111111117", "ean": "111111117", "desc": "Bonus Steuer 7", "quantity": 1, "priceOne": -53, "tax": 7, "group": [], "serialNumber": null, "item_type": "coupon", "reference_id": null, "contract_id": null, "sum": null }, { "id": 5, "parent": null, "articleNumber": "1111111119", "ean": "1111111119", "desc": "Bonus Steuer 19", "quantity": 1, "priceOne": -18, "tax": 19, "group": [], "serialNumber": null, "item_type": "coupon", "reference_id": null, "contract_id": null, "sum": null }], "texts": [], "type": "default" }, "receipt": [{ "type": "separator", "value": { "caption": "Kundenkarte" } }, { "type": "name-value", "value": { "name": "Kartennummer:" "value": "9276004424644352", "decoration": [] } }, { "type": "name-value", "value": { "name": "TA Code:" "value": "30061885", "decoration": [] } }, { "type": "space" }, { "type": "textline", "value": { "text": "Umsatz erfasst:" "decoration": [] } }, { "type": "textline", "value": { "text": "7,25 EUR", "decoration": ["important"] } }, { "type": "space" }, { "type": "textline", "value": { "text": "Bonus:" "decoration": [] } }, { "type": "textline", "value": { "text": "0,72 EUR", "decoration": ["important"] } }, { "type": "space" }, { "type": "textline", "value": { "text": "Aktuelles Guthaben" "decoration": [] } }, { "type": "textline", "value": { "text": "0,72 EUR", "decoration": ["important"] } }], "basket_info": { "sum": 725, "currency": "EUR", "gratuity": null, "missing_sum": 725 }, "idents": [{ "object": "smart.idents", "id": "smi_1", "prefix": "9276", "name": "secucard Kundenkarte", "type": "card", "value": "9276004424644352", "valid": true, "merchantcard": { "object": "loyalty.merchantcards", "id": "MCD_2UXQJ84A62MENH7UWH6QXDYJSBNAA9", "merchant": { "object": "general.merchants" } } }] } ``` -------------------------------- ### General Store Creation Response Sample Source: https://developer.secuconnect.com/api This is a sample JSON response upon successful creation of a general store. It returns the details of the newly created store. ```json { "object": "general.stores", "id": "STO_G6ZOIFP46V02KUJBPDTKK008VIK4QH", "id_old": 1046176, "store_name": null, "merchant": { "object": "general.merchants", "id": "MRC_KLMDFHSWEYQ938WPCJHGF3D74XUMNI" }, "acceptance_point": false, "name": "Musterstadt Muster-Center", "name_raw": "Musterstadt Muster-Center", "facebook_id": "", "has_beacon": false, "open_hours": [ { "open": { "day": 1, "time": "0800" }, "close": { "day": 1, "time": "2300" } }, { "open": { "day": 2, "time": "0800" }, "close": { "day": 2, "time": "2300" } }, { "open": { "day": 3, "time": "0800" }, "close": { "day": 3, "time": "2300" } }, { "open": { "day": 4, "time": "0800" }, "close": { "day": 4, "time": "2300" } }, { "open": { "day": 5, "time": "0800" }, "close": { "day": 5, "time": "2300" } }, { "open": { "day": 6, "time": "0800" }, "close": { "day": 6, "time": "2300" } } ], "open_now": true, "open_time": 321, "phone_number_formatted": "", "url_website": "https://www.example.com/stores/musterstadt-mustercenter" } ``` -------------------------------- ### Start Non-Blocking IBAN Validation Task Request Source: https://developer.secuconnect.com/integration/Validate_the_IBANs.html Initiate a non-blocking IBAN validation task for larger sets of IBANs. This endpoint starts an event action. ```HTTP POST /api/v2/Event/Actions HTTP/1.1 Host: connect-testing.secupay-ag.de Content-Type: application/json Authorization: Bearer htlu0l0m22rsesvh20f7i5d22i Content-Length: 346 { "endpoint": "/Payment/Containers/me/validateSingleIban", "http_method": "POST", "items": [ { "id": 1, "iban": "DE37503240001000000524", "bic": "" }, { "id": 2, "iban": "DE99999999999999999999", "bic": "" } ] } ```