Square Terminal Workflow Question

Questions
1

Hello,

I am new to Square Terminal. I am developing custom pos with .net c#.
I have not received physical ‘Square Terminal’ I ordered for test yet as of now.
Below will be my workflow on Square Terminal on card payment.
Please post any response if I am doing wrong or you have any experience with Terminal Api.
Any response will be greatly appreciated.

  1. Initialize Client
    client = new SquareClient.Builder()
    .Environment(sqEnv) //production or sandbox
    .AccessToken(clientAccessToken) //merchant’s access token
    .Build();

  2. Create Terminal Checkout
    client.TerminalApi.CreateTerminalCheckoutAsync(body: body);
    //amountMoney, tipSettings, checkout, deviceOptions (with deviceId: “ABCD”)
    //deviceId: I don’t have ‘physical terminal’ yet but this (“ABCD”) works for test as of now.

  3. Get Payment (Cannot test because I don’t have ‘Terminal’)
    Please let me know if this is OK.
    //Wait for 5 to 10 seconds until card is inserted by user. Default is 5 min. for terminal checkout to be canceled.
    //After 5 to 10 seconds, get Square.Models.Payment [payment] by calling client.PaymentsApi.GetPaymentAsync(paymentId: _paymentId);
    //_payment id is set by CreateTerminalCheckoutAsync’s response of PaymentIds[0] => Is this OK to use? I cannot test this value because I don’t have ‘Terminal’.
    Question is … Is it ok to use PaymentIds[0] to call [Get payment Api] using Square’s Api.

  4. If [payment] is null, there may be error… then,
    call client.TerminalApi.CancelTerminalCheckoutAsync(checkoutId: _checkoutId); //_checkoutId is from CreateTerminalCheckoutAsync()

  5. If [payment] is not null, card was inserted to ‘Square Terminal’ by user.
    Do save some info and print receipt.

Any response will be greatly appreciated.
Thanks.

2

:wave: That’s great your building with Terminal API. The good news is you can start development prior to receiving a device. This is because the Terminal API supports a collection of special device_id values you can use to simulate terminal checkouts without connecting to a physical Square Terminal. Successful Sandbox requests result in a payment generated in the Sandbox and shown in the Seller Dashboard for your test account.

As for your workflow you may want to listen for Terminal webhooks to be notified when a checkout is updated. Once a checkout is updated with the payment_id you can then call the Payments API with the ID. Also as a backup you may want to occasionally poll for the checkout with GetTerminalCheckout to look for updates on the checkout prior to calling the other APIs. :slightly_smiling_face:

3

Thank you so much for the test device id.

4

Hi I’m new to Square API as well, I copied the code from the Square console for C# but what do i declare client as? i.e. client.TerminalApi.CreateTerminalCheckoutAsync

var amountMoney = new Money.Builder()
.Amount(100L)
.Currency(“USD”)
.Build();

        var tipSettings = new TipSettings.Builder()
          .AllowTipping(false)
          .Build();

        var deviceOptions = new DeviceCheckoutOptions.Builder(deviceId: "221CS12454002683")
          .SkipReceiptScreen(true)
          .CollectSignature(false)
          .TipSettings(tipSettings)
          .Build();

        var appFeeMoney = new Money.Builder()
          .Amount(0L)
          .Currency("USD")
          .Build();

        var checkout = new TerminalCheckout.Builder(amountMoney: amountMoney, deviceOptions: deviceOptions)
          .ReferenceId("2514")
          .PaymentType("CARD_PRESENT")
          .AppFeeMoney(appFeeMoney)
          .Build();

        var body = new CreateTerminalCheckoutRequest.Builder(idempotencyKey: "625c3f5d-f6b9-498c-93f1-7c745f62d80a", checkout: checkout)
          .Build();

        try
        {
            var result = await client.TerminalApi.CreateTerminalCheckoutAsync(body: body);
        }
        catch (ApiException e)
        {
            Console.WriteLine("Failed to make the request");
            Console.WriteLine($"Response Code: {e.ResponseCode}");
            Console.WriteLine($"Exception: {e.Message}");
        }
5

Sorry for the late reply. Below is how to declare and initialize client.

using Square;

//Declaration
private static SquareClient client;
private static Square.Environment sqEnv;
private static string clientAccessToken;
//… and other things follow as you need. You need more than this.

//Get values for sqEnv, clientAccessToken from your database, file, or whatever your application is holding these information but make sure clientAccessToken is ‘strongly encrypted’ using your own method.
//Decrypt clientAccessToken using your own encrypt/decrypt method.

//Initialize client
try
{
sqEnv = Square.Environment.Production; //or Sandbox. Depend on your need.
client = new SquareClient.Builder()
.Environment(sqEnv)
.AccessToken(clientAccessToken)
.Build();
}
catch(ApiException ex)
{
}

//After above returns true, which means client is initialized, then you can process card by calling… var response = client.TerminalApi.CreateTerminalCheckoutAsync(body: body);

//Make sure you set ServicePointManager.SecurityProtocol properly on calling client.TerminalApi.CreateTerminalCheckoutAsync(body:body).

Hope this helps,