# /paymentmethods/apple-pay/v1/transactions/{transactionId}/start

Generates a valid payment session by interacting with Apple Pay servers.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Payments Gateway",
    "description": "Common payments API",
    "version": "1.23.0"
  },
  "security": [
    {
      "oAuth2ClientCredentials": []
    }
  ],
  "servers": [
    {
      "url": "/api/v1/"
    }
  ],
  "paths": {
    "/paymentmethods/apple-pay/v1/transactions/{transactionId}/start": {
      "post": {
        "description": "Generates a valid payment session by interacting with Apple Pay servers.\n",
        "tags": [
          "ApplePay"
        ],
        "operationId": "startApplePayTransaction",
        "parameters": [
          {
            "name": "transactionId",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/Uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StartApplePayPayment"
              }
            }
          }
        },
        "responses": {
          "201": {
            "$ref": "#/components/responses/StartApplePayPayment"
          },
          "4XX": {
            "$ref": "#/components/responses/UserError"
          },
          "5XX": {
            "$ref": "#/components/responses/InternalError"
          }
        },
        "callbacks": {
          "TransactionWebhook": {
            "$ref": "#/components/callbacks/TransactionWebhook"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Uuid": {
        "description": "Unique identifier",
        "type": "string",
        "format": "uuid",
        "minLength": 36,
        "maxLength": 36,
        "example": "8db1e7fa-ba8a-4189-92fd-67a20217443d"
      },
      "Reference": {
        "description": "Identifier from client. This value will be sent in the webhook payload alongside the ID you receive as part of the response of a transaction.",
        "type": "string",
        "minLength": 1,
        "maxLength": 255,
        "example": 20210623130413,
        "default": ""
      },
      "Datetime": {
        "description": "ISO 8601 date and time",
        "type": "string",
        "format": "date-time",
        "minLength": 20,
        "example": "2006-01-02T15:04:05Z"
      },
      "TransactionWebhookEvent": {
        "description": "* `FINALSTATUS` - When the status of the transaction becomes final; it is no longer `OPEN`.\n* `STATUS_CHANGE` - When the status of the transaction has any change.\n",
        "type": "string",
        "enum": [
          "FINALSTATUS",
          "STATUS_CHANGE"
        ],
        "example": "FINALSTATUS"
      },
      "Digest": {
        "description": "Digest of whole message body",
        "type": "string",
        "example": "sha-256=OWM5MDc3ODYwNzdjYjE5NjU0Y2NjMDM4MzEyYzMxZTA5MTAzMDBjYWM1Y2I1ODM4NTdlMDU2MzhiMzE1ZDhjNw==",
        "externalDocs": {
          "description": "Instance Digests in HTTP",
          "url": "https://datatracker.ietf.org/doc/html/rfc3230"
        }
      },
      "StartApplePayPayment": {
        "type": "object",
        "properties": {
          "validationUrl": {
            "description": "The validation URL that is generated by the Apple device.",
            "type": "string",
            "example": "https://apple-pay-gateway-cert.apple.com/paymentservices/startSession"
          },
          "displayName": {
            "description": "The name to display on the the payment sheet. You get this information from the initialize endpoint.",
            "type": "string",
            "example": "My merchant commercial name"
          },
          "domainName": {
            "description": "The domain of the website on which the payment will occur. The value must match the domain from which the request is started. If there is a mismatch between this field and the domain that the Apple device determined, then the Apple Pay session will be terminated by the Apple device (with a generic error message or nothing happens).",
            "type": "string",
            "example": "https://app-domain.tld"
          }
        }
      }
    },
    "responses": {
      "StartApplePayPayment": {
        "description": "ApplePay start session for payment response. The returned response is the opaque Apple Pay merchant session in string format. This response must be passed as-is to the Apple Pay services in the frontend.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "displayName": {
                  "type": "string",
                  "example": "My Merchant display name"
                },
                "domainName": {
                  "type": "string",
                  "example": "my-merchant-domain"
                },
                "epochTimestamp": {
                  "type": "integer",
                  "example": 1689601984961
                },
                "expiresAt": {
                  "type": "integer",
                  "example": 1689601984961
                },
                "merchantIdentifier": {
                  "type": "string",
                  "example": "A25210A72D2148E13005A300DFF6435FB401C317CF84C881D9D4018F67BA7D1E"
                },
                "merchantSessionIdentifier": {
                  "type": "string",
                  "example": "SSHB12847F0ACB6478B9C1140CED6216A91_916523AAED1343F5BC5815E12BEE9250AFFDC1A17C46B0DE5A943F0F94927C24"
                },
                "nonce": {
                  "type": "string",
                  "example": "83ds18s"
                },
                "operationalAnalyticsIdentifier": {
                  "type": "string",
                  "example": "A25210A72D2148E13005A300DFF6435FB401C317CF84C881D9D4018F67BA7D1E"
                },
                "pspId": {
                  "type": "string",
                  "example": "A25210A72D2148E13005A300DFF6435FB401C317CF84C881D9D4018F67BA7D1E"
                },
                "retries": {
                  "type": "integer",
                  "example": 0
                },
                "signature": {
                  "type": "string",
                  "example": "308006092a864886f70d010702a0803080020101310d300b0609608648016503040201308006092a864886f70d0107010000a080308203e330820388a00302010202084c304149519d5436300a06082a8648ce3d040302307a312e302c06035504030c254170706c65204170706c69636174696f6e20496e746567726174696f6e204341202d20473331263024060355040b0c1d4170706c652043657274696669636174696f6e20417574686f7269747931133011060355040a0c0a4170706c6520496e632e310b3009060355040613025553301e170d3139303531383031333235375a170d3234303531363031333235375a305f3125302306035504030c1c6563632d736d702d62726f6b65722d7369676e5f5543342d50524f4431143012060355040b0c0b694f532053797374656d7331133011060355040a0c0a4170706c6520496e632e310b30090603550406130255533059301306072a8648ce3d020106082a8648ce3d03010703420004c21577edebd6c7b2218f68dd7090a1218dc7b0bd6f2c283d846095d94af4a5411b83420ed811f3407e83331f1c54c3f7eb3220d6bad5d4eff49289893e7c0f13a38202113082020d300c0603551d130101ff04023000301f0603551d2304183016801423f249c44f93e4ef27e6c4f6286c3fa2bbfd2e4b304506082b0601050507010104393037303506082b060105050730018629687474703a2f2f6f6373702e6170706c652e636f6d2f6f63737030342d6170706c65616963613330323082011d0603551d2004820114308201103082010c06092a864886f7636405013081fe3081c306082b060105050702023081b60c81b352656c69616e6365206f6e207468697320636572746966696361746520627920616e7920706172747920617373756d65732061636365707461..."
                }
              }
            }
          }
        }
      },
      "InternalError": {
        "description": "Internal server error. This can be caused by an unresponsive backend",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "id",
                "message"
              ],
              "properties": {
                "id": {
                  "$ref": "#/components/schemas/Uuid"
                },
                "message": {
                  "type": "string",
                  "example": "Service Unavailable"
                }
              }
            }
          }
        }
      },
      "UserError": {
        "description": "The user input was incorrect or something illegal was attempted (eg. using a service without having that service configured for the user, or not being authorized)",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "id",
                "message"
              ],
              "properties": {
                "id": {
                  "$ref": "#/components/schemas/Uuid"
                },
                "message": {
                  "type": "string",
                  "example": "no authorization methods provided"
                }
              }
            }
          }
        }
      }
    },
    "callbacks": {
      "TransactionWebhook": {
        "$request.body#/webhooks/-/url": {
          "post": {
            "parameters": [
              {
                "in": "header",
                "name": "Digest",
                "description": "Digest of whole message body",
                "example": "sha-256=M2ZkM2VlMGFlZDViOGE2ZTQ5ZmFiOTJiMWIxZTljZDliNjQ2MGEwYmFmMThiN2JlZWIxZThkZjk5ZTY1ZjgyNQ==",
                "schema": {
                  "$ref": "#/components/schemas/Digest"
                }
              }
            ],
            "requestBody": {
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "required": [
                      "createdAt",
                      "event",
                      "transaction",
                      "reference"
                    ],
                    "properties": {
                      "createdAt": {
                        "$ref": "#/components/schemas/Datetime"
                      },
                      "event": {
                        "$ref": "#/components/schemas/TransactionWebhookEvent"
                      },
                      "transaction": {
                        "$ref": "#/components/schemas/Uuid"
                      },
                      "reference": {
                        "$ref": "#/components/schemas/Reference"
                      }
                    }
                  }
                }
              }
            },
            "responses": {
              "2XX": {
                "description": "Webhook successful."
              },
              "default": {
                "description": "Webhook failed. Will be retried several times."
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "oAuth2ClientCredentials": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "/api/v1/authorization/oauth2/token",
            "scopes": {}
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 103,
      "1": 234,
      "2": 76,
      "3": 191,
      "4": 145,
      "5": 198,
      "6": 48,
      "7": 79,
      "8": 46,
      "9": 249,
      "10": 185,
      "11": 249
    }
  }
}
```